From 630392717d751b7b2dfc7314322893ac3ebc6bb0 Mon Sep 17 00:00:00 2001 From: Federico Grandi Date: Sun, 17 Jan 2021 14:00:40 +0100 Subject: [PATCH 1/2] docs: improve formatting Run Prettier, fix ESLint errors, improve indentation --- docs/api/fetch-data.md | 44 +++++----- docs/api/introduction.md | 15 ++-- docs/api/post-data.md | 25 +++--- docs/api/using-webhooks.md | 162 +++++++++++++++++++------------------ package.json | 2 +- 5 files changed, 131 insertions(+), 117 deletions(-) diff --git a/docs/api/fetch-data.md b/docs/api/fetch-data.md index 26ebd0f..da928c5 100644 --- a/docs/api/fetch-data.md +++ b/docs/api/fetch-data.md @@ -1,33 +1,35 @@ # Fetch informations ### IMPORTANT + **Please make sure to read the introduction before request help !** -*Fetching data must be do with a GET request* +_Fetching data must be do with a GET request_ ##### fetch global statistics about a bot `GET /bots/:botID/`
**Output:** + ```json { -"name":"mybot#0000", -"id":"000000000", -"avatar":"https://cdn.discordapp.com/avatars/id/avatar.png", -"prefix":"!", -"library":"library", -"owner":"exemple#0000", -"ownerid":"00000000000", -"short_desc":"The short desc", -"long_desc":"the bot's description", -"tags":["music", "info", "traffic"], -"support":"https://discord.gg/support", -"website":"https://bladebotlist.xyz", -"github":"https://github.com/bladebotlist", -"servers":"n/a or a number", -"status":"approved/waiting/declined", -"votes": "number", -"certified": "boolean" + "name": "mybot#0000", + "id": "000000000", + "avatar": "https://cdn.discordapp.com/avatars/id/avatar.png", + "prefix": "!", + "library": "library", + "owner": "exemple#0000", + "ownerid": "00000000000", + "short_desc": "The short desc", + "long_desc": "the bot's description", + "tags": ["music", "info", "traffic"], + "support": "https://discord.gg/support", + "website": "https://bladebotlist.xyz", + "github": "https://github.com/bladebotlist", + "servers": "n/a or a number", + "status": "approved/waiting/declined", + "votes": "number", + "certified": "boolean" } ``` @@ -42,10 +44,10 @@ `GET /bots/:botID/votes/:userID` **Output:** + ```json { -"voted":"boolean", -"votes":"number of votes" + "voted": "boolean", + "votes": "number of votes" } ``` - diff --git a/docs/api/introduction.md b/docs/api/introduction.md index 0b7ad9a..6f1cc9e 100644 --- a/docs/api/introduction.md +++ b/docs/api/introduction.md @@ -1,14 +1,18 @@ # Introduction + ### Reference + **To interact with the bladebotlist api you will need these things** -#### Base urls -`https://bladebotlist.xyz/api/` **-** [Current] [Working] +#### Base urls +`https://bladebotlist.xyz/api/` **-** [Current][working] ### Authentication + #### **Why need authorization ?** -*For security reasons we need to make some endpoints only accessible while you add a authorization token on headers* + +_For security reasons we need to make some endpoints only accessible while you add a authorization token on headers_ **Example:** | Header | Value | @@ -16,6 +20,7 @@ | **Authorization** | `MyPowerFulAPIkeyToBeAuthenitificated` | ### Bot Statistics -*We highly recommands you to use our [**NPM MODULE**](https://npmjs.com/package/bbl-api) this will make data posting easier* -**Posting data is also recommanded for big bots and bots which want to be [certified](https://bladebotlist.xyz/certify)** \ No newline at end of file +_We highly recommands you to use our [**NPM MODULE**](https://npmjs.com/package/bbl-api) this will make data posting easier_ + +**Posting data is also recommanded for big bots and bots which want to be [certified](https://bladebotlist.xyz/certify)** diff --git a/docs/api/post-data.md b/docs/api/post-data.md index 575df1f..6e5e264 100644 --- a/docs/api/post-data.md +++ b/docs/api/post-data.md @@ -5,7 +5,6 @@ **READ MODULE'S DOCS** [NODE.js Module](https://www.npmjs.com/package/bbl-api) - ### Manual post #### Important @@ -14,26 +13,26 @@ Things with \* are mandatory **Please add these things in headers** -| Key | Value | -|---|---| -| authorization* | Bot's API KEY | -| Content-Type | application/json | +| Key | Value | +| --------------- | ---------------- | +| authorization\* | Bot's API KEY | +| Content-Type | application/json | -**Please add these things in body __as json__** +**Please add these things in body **as json**** -| Key | Value | -|---|---| -| servercount* | number of servers | -| shardcount | number of shards if sharded | +| Key | Value | +| ------------- | --------------------------- | +| servercount\* | number of servers | +| shardcount | number of shards if sharded | **Then you will need to do this request** `POST /bots/:botID/stats` -*Output:*
+_Output:_
```json { - ok:"successfully posted servercount servers for the bot botname !" + "ok": "successfully posted servercount servers for the bot botname !" } -``` \ No newline at end of file +``` diff --git a/docs/api/using-webhooks.md b/docs/api/using-webhooks.md index 29c9d21..8c57ed2 100644 --- a/docs/api/using-webhooks.md +++ b/docs/api/using-webhooks.md @@ -5,125 +5,133 @@ ### Create the webhook 1. Go to server settings - ![server settings](http://cdn.bladebotlist.xyz/SDcWC1MX) + ![server settings](http://cdn.bladebotlist.xyz/SDcWC1MX) 2. Go to Integrations - ![integrations](http://cdn.bladebotlist.xyz/aVpU3C6l) + ![integrations](http://cdn.bladebotlist.xyz/aVpU3C6l) 3. Click on "Create Webhook" - ![create webhook](http://cdn.bladebotlist.xyz/FwWo8791) + ![create webhook](http://cdn.bladebotlist.xyz/FwWo8791) 4. Edit the name (1), The channel (2) and the avatar (3) - ![Edut name, channel, avatar](http://cdn.bladebotlist.xyz/UZ87O0Vu) + ![Edut name, channel, avatar](http://cdn.bladebotlist.xyz/UZ87O0Vu) 5. And finally copy the webhook url - ![Copy webhook](http://cdn.bladebotlist.xyz/d1Jk5KFG) + ![Copy webhook](http://cdn.bladebotlist.xyz/d1Jk5KFG) 6. If you did everything you must got an url like `https://discord.com/api/webhooks/000111222333444555/T0K3EN` ### Add it to BladeBotList 1. Go to `https://bladebotlist.xyz/bot/:YOURBOTID/edit/webhook` - ![Bot Webhook page](http://cdn.bladebotlist.xyz/LDEOkqIU) + ![Bot Webhook page](http://cdn.bladebotlist.xyz/LDEOkqIU) 2. Paste the webhook url in the "Discord Webhook" field - ![Bot webhook](http://cdn.bladebotlist.xyz/xo1N86cf) + ![Bot webhook](http://cdn.bladebotlist.xyz/xo1N86cf) 3. Click on "Edit Webhook" and you're done ! - ![Edit webhook](http://cdn.bladebotlist.xyz/J2lVoD8e) + ![Edit webhook](http://cdn.bladebotlist.xyz/J2lVoD8e) 4. Test it by voting for the bot ! - ![Vote demo](http://cdn.bladebotlist.xyz/TT0TMge7) - + ![Vote demo](http://cdn.bladebotlist.xyz/TT0TMge7) ## Post to Custom Webhook server ### Using the BBL-API module [Default config](https://github.com/BladeBotList/bbl-api/blob/master/examples/postdata.js) -```js -const BBL = require("../app"); +```js +const BBL = require('../app'); const client = new BBL( - "", // BOT_ID - "", // API_KEY, - { - server_count: "20", // number of servers ie: discordjs v12 => client.guilds.cache.size - shard_count: "0", // number of shards, null if not defined - interval: 300000, // interval bethween each post - }); + '', // BOT_ID + '', // API_KEY, + { + server_count: '20', // number of servers ie: discordjs v12 => client.guilds.cache.size + shard_count: '0', // number of shards, null if not defined + interval: 300000, // interval bethween each post + } +); +client.on('ready', () => console.log('Client is started !')); // when the module is loaded and ready to post data -client.on("ready", () => console.log("Client is started !")); // when the module is loaded and ready to post data +client.on('debug', log => console.log(log)); // debug messages for developers, not required -client.on("debug", (log) => console.log(log)) // debug messages for developers, not required +client.on('update', () => console.log('Stats updated !')); // event when autopost or manual post -client.on("update", () => console.log("Stats updated !")); // event when autopost or manual post - -client.on("error", (error) => console.log(`Something was wrong when the module has posted stats: ${error}`)); // complete reports about errors like invalid api key or bot id +client.on('error', error => console.log( + `Something was wrong when the module has posted stats: ${error}` +)); // complete reports about errors like invalid api key or bot id ``` 1. Add in the module config this: + ```json - webhook: { - status: true, - port: 6060, - password: "youshallnotpass", - endpoint:"/hook" - } +"webhook": { + "status": true, + "port": 6060, + "password": "youshallnotpass", + "endpoint": "/hook" +} ``` + 2. Change the port if need (default: 3000) 3. Change the password or left empty to disable (Not recommanded at all) (default: none) 4. Change the endpoint if you want (default: /hook) 5. [Final code](https://github.com/BladeBotList/bbl-api/blob/master/examples/webhooks.js) + ```js -const BBL = require("../app"); +const BBL = require('../app'); const client = new BBL( - "", // BOT_ID - "", // API_KEY, - { - server_count: "3000", - shard_count: "20", - interval: 300000, - webhook: { - status: true, - port: 6060, - password: "youshallnotpass", - endpoint:"/hook" - } - }); - - -client.on("ready", () => console.log("Client is started !")); // when the module is loaded and ready to post data - -client.on("debug", (log) => console.log(log)) - -client.on("update", () => console.log("Stats updated !")); // autopost or manual post - -client.on("error", (error) => console.log(`Something was wrong when the module has posted stats: ${error}`)); // complete reports about errors like invalid api key or bot id - -client.on("vote", (out) => { -/* -out must looks like -{ - "userid":355995885085392896, - "usertag":`HiiZun#0001`, - "username":`HiiZun`, - "userdiscriminator":`0001`, - "botID":`643499304950038539`, - "date":1603908629750 -} -*/ - - console.log(`Whoohoo ! ${out.usertag} just voted !`) -}) + '', // BOT_ID + '', // API_KEY, + { + server_count: '3000', + shard_count: '20', + interval: 300000, + webhook: { + status: true, + port: 6060, + password: 'youshallnotpass', + endpoint: '/hook', + }, + } +); + +client.on('ready', () => console.log('Client is started !')); // when the module is loaded and ready to post data + +client.on('debug', log => console.log(log)); + +client.on('update', () => console.log('Stats updated !')); // autopost or manual post + +client.on('error', error => console.log( + `Something was wrong when the module has posted stats: ${error}` +)); // complete reports about errors like invalid api key or bot id + +client.on('vote', out => { + /* + `out` must looks like this: + { + "userid":355995885085392896, + "usertag":`HiiZun#0001`, + "username":`HiiZun`, + "userdiscriminator":`0001`, + "botID":`643499304950038539`, + "date":1603908629750 + } + */ + + console.log(`Whoohoo ! ${out.usertag} just voted !`); +}); ``` -6. the event "vote" is emitted when you receve a bot + +6. the event "vote" is emitted when you receve a bot 7. Go to `https://bladebotlist.xyz/bot/:BOTID/edit/webhook`, and put url as: `http://:/` ex: http://mybot.bladebotlist.xyz:6060/hook - ![Example](http://cdn.bladebotlist.xyz/PfgIV682) + ![Example](http://cdn.bladebotlist.xyz/PfgIV682) 8. Add the password if you added it (you can seee it by clicking on "show password") - ![Password example](http://cdn.bladebotlist.xyz/HDuEaSR5) + ![Password example](http://cdn.bladebotlist.xyz/HDuEaSR5) 9. And finally test ! - ![](http://cdn.bladebotlist.xyz/XDIwUSSV) + ![](http://cdn.bladebotlist.xyz/XDIwUSSV) ### Using custom Webserver/Library/Code **We don't give support for custom webhooks** -__Informations:__ -- Requests are made as POST -- we proivde password in headers -- data is in the body +**Informations:** + +- Requests are made as POST +- we proivde password in headers +- data is in the body diff --git a/package.json b/package.json index 1ef33e5..965927e 100644 --- a/package.json +++ b/package.json @@ -6,7 +6,7 @@ "lint": "eslint . --ext js,md,vue", "serve": "vuepress dev docs", "build": "NODE_ENV=production vuepress build docs", - "devbuild":"vuepress build docs" + "devbuild": "vuepress build docs" }, "repository": "https://github.com/bladebotlist/docs.git", "author": "HiiZun", From 66cec9233b9b8f854cf6076c40d61b7c666590fb Mon Sep 17 00:00:00 2001 From: Federico Grandi Date: Sun, 17 Jan 2021 14:21:05 +0100 Subject: [PATCH 2/2] docs: update docs Improve styling & Markdown hierarchy, use common terms & symbols --- docs/api/fetch-data.md | 16 ++++++++-------- docs/api/introduction.md | 14 ++++++-------- docs/api/post-data.md | 34 +++++++++++++++------------------- 3 files changed, 29 insertions(+), 35 deletions(-) diff --git a/docs/api/fetch-data.md b/docs/api/fetch-data.md index da928c5..a203649 100644 --- a/docs/api/fetch-data.md +++ b/docs/api/fetch-data.md @@ -2,14 +2,14 @@ ### IMPORTANT -**Please make sure to read the introduction before request help !** +**Please make sure to read the introduction before request help !** +_Fetching data must be done with a GET request_ -_Fetching data must be do with a GET request_ +## Fetch global statistics about a bot -##### fetch global statistics about a bot +`GET /bots/:botID/` -`GET /bots/:botID/`
-**Output:** +Response: ```json { @@ -33,17 +33,17 @@ _Fetching data must be do with a GET request_ } ``` -##### Fetch a array of bots in the botlist +## Fetch a array of bots in the botlist `GET /bots` **PRIVATE ENDPOINT** -##### Fetch if a user has voted for a bot +## Fetch if a user has voted for a bot `GET /bots/:botID/votes/:userID` -**Output:** +Response: ```json { diff --git a/docs/api/introduction.md b/docs/api/introduction.md index 6f1cc9e..503b1c4 100644 --- a/docs/api/introduction.md +++ b/docs/api/introduction.md @@ -1,18 +1,16 @@ # Introduction -### Reference +## Reference -**To interact with the bladebotlist api you will need these things** - -#### Base urls +### Base urls `https://bladebotlist.xyz/api/` **-** [Current][working] ### Authentication -#### **Why need authorization ?** +#### **Why do I need authorization?** -_For security reasons we need to make some endpoints only accessible while you add a authorization token on headers_ +_For security reasons we need to make some endpoints only accessible while you add a authorization token on headers._ **Example:** | Header | Value | @@ -21,6 +19,6 @@ _For security reasons we need to make some endpoints only accessible while you a ### Bot Statistics -_We highly recommands you to use our [**NPM MODULE**](https://npmjs.com/package/bbl-api) this will make data posting easier_ +_We highly recommands you to use our [**NPM MODULE**](https://npmjs.com/package/bbl-api), this will make data posting easier._ -**Posting data is also recommanded for big bots and bots which want to be [certified](https://bladebotlist.xyz/certify)** +**Posting data is also recommanded for big bots and bots which want to be [certified](https://bladebotlist.xyz/certify).** diff --git a/docs/api/post-data.md b/docs/api/post-data.md index 6e5e264..96f22f8 100644 --- a/docs/api/post-data.md +++ b/docs/api/post-data.md @@ -1,35 +1,31 @@ # Post informations -## Using module +## Using our module -**READ MODULE'S DOCS** +Read the package docs before using it! [NODE.js Module](https://www.npmjs.com/package/bbl-api) -### Manual post +## Posting manually -#### Important +### Headers -Things with \* are mandatory +| Key | Value | +| ------------- | ---------------- | +| Authorization | Bot's API KEY | +| Content-Type? | application/json | -**Please add these things in headers** +### Body -| Key | Value | -| --------------- | ---------------- | -| authorization\* | Bot's API KEY | -| Content-Type | application/json | +| Key | Value | +| ------------ | ---------------------------- | +| server_count | number of servers | +| shard_count? | number of shards, if sharded | -**Please add these things in body **as json**** - -| Key | Value | -| ------------- | --------------------------- | -| servercount\* | number of servers | -| shardcount | number of shards if sharded | - -**Then you will need to do this request** +### Endpoint `POST /bots/:botID/stats` -_Output:_
+### Response ```json {