diff --git a/website/docs/Contributing.mdx b/website/docs/Contributing.mdx index 28795965..f33d29a3 100644 --- a/website/docs/Contributing.mdx +++ b/website/docs/Contributing.mdx @@ -4,8 +4,260 @@ title: How to Contribute sidebar_position: 1 --- -:::caution Keep in mind! +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! -This page is WIP. It will be built up to explain how you can contribute to Discord API Types, and what to keep in mind! +:::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: + +![An image showing the style of comment the automatic deno checker reports](./images/deno_types_out_of_sync.png) + +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 you +need to keep in mind when contributing. + +```bash {5,7-9,12-13,15-19} +├── 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 mdule 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. diff --git a/website/docs/Introduction.mdx b/website/docs/Introduction.mdx index 602b5147..4532dcc2 100644 --- a/website/docs/Introduction.mdx +++ b/website/docs/Introduction.mdx @@ -28,7 +28,7 @@ Discord API Types is a community-maintained project that brings API types for Di ## Installation -Install with [npm](https://www.npmjs.com/) / [yarn](https://yarnpkg.com) / [pnpm](https://pnpm.js.org/): +Install with [`npm`](https://www.npmjs.com/) / [`yarn`](https://yarnpkg.com) / [`pnpm`](https://pnpm.js.org/): ```bash npm2yarn2pnpm npm install discord-api-types diff --git a/website/docs/images/deno_types_out_of_sync.png b/website/docs/images/deno_types_out_of_sync.png new file mode 100644 index 00000000..e679b2c1 Binary files /dev/null and b/website/docs/images/deno_types_out_of_sync.png differ diff --git a/website/src/css/custom.scss b/website/src/css/custom.scss index fdad6eb3..2d97ca05 100644 --- a/website/src/css/custom.scss +++ b/website/src/css/custom.scss @@ -22,6 +22,7 @@ --ifm-navbar-link-active-color: #e5e7eb; --ifm-navbar-link-hover-color: #e5e7eb; --ifm-font-weight-semibold: 700; + --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1); @media screen and (max-width: 997px) { --ifm-menu-color: var(--ifm-navbar-link-color); @@ -44,17 +45,7 @@ html[data-theme='dark'] { --ifm-background-color: #1d1d1d; --ifm-navbar-background-color: #4752c4; --ifm-link-color: hsl(235, 85%, 82%); -} - -.docusaurus-highlight-code-line { - background-color: rgba(0, 0, 0, 0.1); - display: block; - margin: 0 calc(-1 * var(--ifm-pre-padding)); - padding: 0 var(--ifm-pre-padding); -} - -html[data-theme='dark'] .docusaurus-highlight-code-line { - background-color: rgba(0, 0, 0, 0.3); + --docusaurus-highlighted-code-line-bg: rgba(255, 255, 255, 0.1); } .footer--dark { diff --git a/website/versioned_docs/version-0.33.0/Contributing.mdx b/website/versioned_docs/version-0.33.0/Contributing.mdx index 28795965..f33d29a3 100644 --- a/website/versioned_docs/version-0.33.0/Contributing.mdx +++ b/website/versioned_docs/version-0.33.0/Contributing.mdx @@ -4,8 +4,260 @@ title: How to Contribute sidebar_position: 1 --- -:::caution Keep in mind! +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! -This page is WIP. It will be built up to explain how you can contribute to Discord API Types, and what to keep in mind! +:::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: + +![An image showing the style of comment the automatic deno checker reports](./images/deno_types_out_of_sync.png) + +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 you +need to keep in mind when contributing. + +```bash {5,7-9,12-13,15-19} +├── 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 mdule 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. diff --git a/website/versioned_docs/version-0.33.0/Introduction.mdx b/website/versioned_docs/version-0.33.0/Introduction.mdx index b830b100..4532dcc2 100644 --- a/website/versioned_docs/version-0.33.0/Introduction.mdx +++ b/website/versioned_docs/version-0.33.0/Introduction.mdx @@ -28,7 +28,7 @@ Discord API Types is a community-maintained project that brings API types for Di ## Installation -Install with [npm](https://www.npmjs.com/) / [yarn](https://yarnpkg.com) / [pnpm](https://pnpm.js.org/): +Install with [`npm`](https://www.npmjs.com/) / [`yarn`](https://yarnpkg.com) / [`pnpm`](https://pnpm.js.org/): ```bash npm2yarn2pnpm npm install discord-api-types @@ -42,7 +42,7 @@ the `*` represents the API version. Below are some examples -```javascript showLineNumbers +```typescript showLineNumbers /** * @type {import('discord-api-types/v10').APIUser} */ @@ -52,7 +52,7 @@ the `*` represents the API version. Below are some examples -```javascript showLineNumbers +```typescript showLineNumbers /** * @type {import('discord-api-types/v10').APIUser} */ @@ -126,32 +126,32 @@ import { APIUser } from 'https://cdn.skypack.dev/discord-api-types/v10?dts'; 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 `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 `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. +- 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` where the type represents what it will return. + - For endpoint options, they will follow the following structure: + `REST` where the type represents what it will return. - - For example, `RESTPostAPIChannelMessageJSONBody` or `RESTGetAPIGatewayBotInfoResult`. + - 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 `RESTOAuth2` + - 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 `RESTOAuth2` - - If a type ends with `Result`, then it represents the expected result by calling its accompanying route. + - 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. + - 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). +- 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. +- 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 diff --git a/website/versioned_docs/version-0.33.0/images/deno_types_out_of_sync.png b/website/versioned_docs/version-0.33.0/images/deno_types_out_of_sync.png new file mode 100644 index 00000000..e679b2c1 Binary files /dev/null and b/website/versioned_docs/version-0.33.0/images/deno_types_out_of_sync.png differ diff --git a/website/versioned_docs/version-0.33.1/Contributing.mdx b/website/versioned_docs/version-0.33.1/Contributing.mdx index 28795965..f33d29a3 100644 --- a/website/versioned_docs/version-0.33.1/Contributing.mdx +++ b/website/versioned_docs/version-0.33.1/Contributing.mdx @@ -4,8 +4,260 @@ title: How to Contribute sidebar_position: 1 --- -:::caution Keep in mind! +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! -This page is WIP. It will be built up to explain how you can contribute to Discord API Types, and what to keep in mind! +:::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: + +![An image showing the style of comment the automatic deno checker reports](./images/deno_types_out_of_sync.png) + +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 you +need to keep in mind when contributing. + +```bash {5,7-9,12-13,15-19} +├── 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 mdule 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. diff --git a/website/versioned_docs/version-0.33.1/Introduction.mdx b/website/versioned_docs/version-0.33.1/Introduction.mdx index ec8f9f48..4532dcc2 100644 --- a/website/versioned_docs/version-0.33.1/Introduction.mdx +++ b/website/versioned_docs/version-0.33.1/Introduction.mdx @@ -28,7 +28,7 @@ Discord API Types is a community-maintained project that brings API types for Di ## Installation -Install with [npm](https://www.npmjs.com/) / [yarn](https://yarnpkg.com) / [pnpm](https://pnpm.js.org/): +Install with [`npm`](https://www.npmjs.com/) / [`yarn`](https://yarnpkg.com) / [`pnpm`](https://pnpm.js.org/): ```bash npm2yarn2pnpm npm install discord-api-types @@ -42,7 +42,7 @@ the `*` represents the API version. Below are some examples -```javascript showLineNumbers +```typescript showLineNumbers /** * @type {import('discord-api-types/v10').APIUser} */ @@ -52,7 +52,7 @@ the `*` represents the API version. Below are some examples -```javascript showLineNumbers +```typescript showLineNumbers /** * @type {import('discord-api-types/v10').APIUser} */ diff --git a/website/versioned_docs/version-0.33.1/images/deno_types_out_of_sync.png b/website/versioned_docs/version-0.33.1/images/deno_types_out_of_sync.png new file mode 100644 index 00000000..e679b2c1 Binary files /dev/null and b/website/versioned_docs/version-0.33.1/images/deno_types_out_of_sync.png differ