From 60f69cba2378f458cee1b2020abfb31fc3da583e Mon Sep 17 00:00:00 2001 From: Vlad Frangu Date: Sun, 23 Aug 2020 02:15:41 +0300 Subject: [PATCH] chore: actually finalize repository setup --- .github/workflows/codequality.yml | 4 --- README.md | 58 ++++++++++++++++++++++--------- package.json | 4 +-- tsconfig.json | 2 +- 4 files changed, 44 insertions(+), 24 deletions(-) diff --git a/.github/workflows/codequality.yml b/.github/workflows/codequality.yml index fe65ac58..59616769 100644 --- a/.github/workflows/codequality.yml +++ b/.github/workflows/codequality.yml @@ -28,8 +28,6 @@ jobs: run: yarn --ignore-scripts --frozen-lockfile - name: Run ESLint uses: icrawl/action-eslint@v1 - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: custom-glob: '{v*,default,common}/**' @@ -52,5 +50,3 @@ jobs: run: yarn --ignore-scripts --frozen-lockfile - name: Run TSC uses: icrawl/action-tsc@v1 - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/README.md b/README.md index bd8b4bc4..d1a1fec1 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,49 @@ -# Discord API Types +

Discord API Types

-Simple type defitions for the [Discord API](https://discord.com/developers/docs/intro) +[![GitHub](https://img.shields.io/github/license/discordjs/discord-api-types)](https://github.com/discordjs/discord-api-types/blob/main/LICENSE.md) +[![npm](https://img.shields.io/npm/v/discord-api-types?color=crimson&logo=npm)](https://www.npmjs.com/package/discord-api-types) +[![Patreon Donate](https://img.shields.io/badge/patreon-donate-brightgreen.svg?label=Donate%20with%20Patreon&logo=patreon&colorB=F96854&link=https://www.patreon.com/vladfrangu)](https://www.patreon.com/vladfrangu) +[![Ko-fi Donate](https://img.shields.io/badge/kofi-donate-brightgreen.svg?label=Donate%20with%20Ko-fi&logo=ko-fi&colorB=F16061&link=https://ko-fi.com/wolfgalvlad&logoColor=FFFFFF)](https://ko-fi.com/wolfgalvlad) -## How it's done +Simple type definitions for the [Discord API](https://discord.com/developers/docs/intro). + +## Installation + +Install with [npm](https://www.npmjs.com/) / [yarn](https://yarnpkg.com) / [pnpm](https://pnpm.js.org/): + +```sh +npm install discord-api-types +yarn add discord-api-types +pnpm add discord-api-types +``` + +## 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 referred to the Gateway -- Everything exported with the `REST` prefix represents data that ONLY comes from or is directly reffered to the REST API - - For endpoint options, they will follow the following structure: `RESTBody|Result>` where the type represents what it will return - - If a type ends with `Result`, then it represents the expected result by calling it's 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 exported things from all versions - common throughout all API versions - that will simply be exported as is and are present in the `common` directory. They will still be prefixed with `REST` or `Gateway` accordingly. +- Everything exported with the `API` prefix represents a payload you may get from the REST API *or* the Gateway. -**Warning**: This package documents just KNOWN (and documented) properties. Anything that isn't documented will NOT be added to this package (unless said properties are already PR'd to Discord's [API Documentation repository](https://github.com/discord/discord-api-docs) or known through other means and have received the green light to be used) +- Everything exported with the `Gateway` prefix represents data that ONLY comes from or is directly related to the Gateway. -## How to use +- Everything exported with the `REST` prefix represents data that ONLY comes from or is directly related to the REST API. -You can require / import the module directly, which will give you the latest types as of the current API version. This is considered the `default` version and may break at any point in time. + - For endpoint options, they will follow the following structure: `REST` where the type represents what it will return. + + - For example, `RESTPostAPIChannelMessageJSONBody` or `RESTGetAPIGatewayBotInfoResult`. + + - If a type ends with `Result`, then it represents the expected result by calling its accompanying route. + + - Types that are exported as `never` usually mean the result will be a `204 No Content`, so you can safely ignore it. This does **not** account for errors. + +- Anything else that is miscellaneous will be exported based on what it represents (for example the `REST` route object). + +- There may be types exported that are identical for all versions. These will be exported as is and can be found in the `common` directory. They will still be prefixed accordingly as described above. + +**Warning**: This package documents just KNOWN (and documented) properties. Anything that isn't documented will NOT be added to this package (unless said properties are in an open Pull Request to Discord's [API Documentation repository](https://github.com/discord/discord-api-docs) or known through other means *and have received the green light to be used*). For clarification's sake, this means that properties that are only known through the process of datamining and have not yet been confirmed in a way as described will NOT be included. + +## Usage + +You can `require` / `import` the module directly, which will give you the latest types as of the current API version. This is considered the `default` version and will be updated according to Discord's default API version; this means it may break at any point in time. > We **strongly recommend** you use a version when importing this module! This will prevent breaking changes when updating the module. @@ -28,17 +52,17 @@ const { APIUserData } = require('discord-api-types'); ``` ```ts -// TypeScript support +// TypeScript/ES Module support import { APIUserData } from 'discord-api-types' ``` -You may also add the API version you want to use by appending `/v*`, where the * represends the API version +You should instead consider adding the API version you want to target by appending `/v*`, where the `*` represends the API version. ```js const { APIUserData } = require('discord-api-types/v6'); ``` ```ts -// TypeScript support +// TypeScript/ES Module support import { APIUserData } from 'discord-api-types/v6'; ``` diff --git a/package.json b/package.json index 55f1f41c..776e1015 100644 --- a/package.json +++ b/package.json @@ -28,7 +28,7 @@ "common/**/*.d.ts" ], "engines": { - "node": ">12" + "node": ">=12" }, "devDependencies": { "@commitlint/cli": "^9.1.2", @@ -47,7 +47,7 @@ }, "repository": { "type": "git", - "url": "https://github.com/vladfrangu/discord-api-types" + "url": "https://github.com/discordjs/discord-api-types" }, "husky": { "hooks": { diff --git a/tsconfig.json b/tsconfig.json index 0f795611..3120d938 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -10,7 +10,7 @@ "declarationMap": true, "noUnusedLocals": true, "removeComments": false, - "target": "esnext", + "target": "ES2019", "importsNotUsedAsValues": "error" }, "exclude": [