Way better documentation

SCDerox · Oct 5, 2021 · 1e2fa51 · 1e2fa51
1 parent 16b1af7
commit 1e2fa51
Show file tree

Hide file tree

Showing 8 changed files with 587 additions and 84 deletions.
diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
@@ -0,0 +1,2 @@
+patreon: scnetwork
+custom: [ 'https://bunq.me/scderox', 'https://paypal.me/therealscderox' ]
diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml
@@ -0,0 +1,21 @@
+name: Build gen-doc
+
+on:
+  push:
+  workflow_dispatch:
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install dependencies
+        run: npm install
+      - name: Build gen-doc
+        run: npx jsdoc -c jsdoc.conf.json
+      - name: Commit & Push
+        uses: actions-js/push@master
+        with:
+          github_token: ${{ secrets.GH_TOKEN }}
+          message: generated documentation
+          branch: main
diff --git a/Message.js b/Message.js
@@ -1,24 +1,41 @@
 const centra = require('@aero/centra');
 
+/**
+ * Represents a discord-message
+ */
 class Message {
+    /**
+     * Represents a discord-message
+     * @param {Object} messageData Raw API-Data from Discord
+     * @param {URL} webhookurl Webhook-URL this message belongs to
+     */
     constructor(messageData, webhookurl) {
         this.webhookUrl = webhookurl;
         for (const data in messageData) {
             this[data] = messageData[data];
         }
     }
 
+    /**
+     * Deletes this message
+     * @return {Promise}
+     */
     async delete() {
         const res = await centra(this.webhookUrl + `/messages/${this.id}`, 'DELETE')
             .header('Content-Type', 'application/json')
             .send('form');
-        if (res.statusCode !== 204) {
-            console.error(`Something went wrong while deleting the message ${this.id} with the webhook ${this.webhookUrl}. Here is the answer from discord: `, res.body.toString());
-            return false;
-        }
+        if (res.statusCode !== 204) throw new Error(`Something went wrong while deleting the message ${this.id} with the webhook ${this.webhookUrl}. Here is the answer from discord: ` + res.body.toString());
         return true;
     }
 
+    /**
+     * Edits this message
+     * @param {String} content Content of this message
+     * @param {Array<Object>} embeds  Array of [Embed-Objects](https://discord.com/developers/docs/resources/channel#embed-object)
+     * @param {Object} allowedMentions  [Allowed-Mentions-Object](https://discord.com/developers/docs/resources/channel#allowed-mentions-object)
+     * @param {Array} components  [Message-Component-Object](https://discord.com/developers/docs/interactions/message-components#component-object). ⚠ This will only work, if your webhook is owned by an application.
+     * @return {Promise<Message>} New message
+     */
     async edit(content, embeds = [], allowedMentions = {}, components = []) {
         const res = await centra(this.webhookUrl + `/messages/${this.id}`, 'PATCH').body({
             content: content,
@@ -28,10 +45,7 @@ class Message {
         })
             .header('Content-Type', 'application/json')
             .send('form');
-        if (res.statusCode === 204) {
-            console.error(`Something went wrong while editing the message ${this.id} with the webhook ${this.webhookUrl}. Here is the answer from discord: `, res.body.toString());
-            return false;
-        }
+        if (res.statusCode === 204) throw new Error(`Something went wrong while editing the message ${this.id} with the webhook ${this.webhookUrl}. Here is the answer from discord: ` + res.body.toString());
         return new Message(JSON.parse(res.body.toString()), this.webhookUrl);
     }
 }

diff --git a/README.md b/README.md
@@ -1,6 +1,7 @@
 # simple-discord-webhooks
 
 <p align="center"><a href="https://nodei.co/npm/simple-discord-webhooks/"><img alt="npm package stats" src="https://nodei.co/npm/simple-discord-webhooks.png"></a></p>
+<p align="center"><a href="https://github.com/scderox/simple-discord-webhooks?sponsor=1">&hearts; Sponsor</a> or <a href="https://github.com/SCDerox/simple-discord-webhooks">★ Star</a></p>
 
 # Features
 
@@ -44,51 +45,7 @@ message.edit('Hello there!').then(() => console.log('Edited message'))
 ```
 
 # API
-
-* Class: `Webhook(url, username = null, avatarUrl = null)`
-    * function `send(content, embeds = [], allowedMentions = {}, tts = false)` - Sends a message
-        * content (string): Content of the message
-        * embeds (array, optional): Array
-          of [Embed-Objects](https://discord.com/developers/docs/resources/channel#embed-object)
-        * allowedMentions (object, optional):
-          A [Allowed-Mentions-Object](https://discord.com/developers/docs/resources/channel#allowed-mentions-object)
-        * tts (boolean, optional): Set to `true` to enable TTS.
-        * components (array, optional): Array
-          of [message components](https://discord.com/developers/docs/interactions/message-components#component-object).
-          ⚠ This will only work, if your webhook is owned by an application.
-        * Returns `Promise<Message>` (with all the values
-          from [here](https://discord.com/developers/docs/resources/channel#message-object))
-    * function `edit(name = null, base64Avatar = null)` - Edits the webhook object
-        * name (string, optional): New username of the webhook
-        * base64Avatar (base64String (string), optional): [Base64](https://en.wikipedia.org/wiki/Base64) -String of your
-          image. If you don't know how to use this, please google `Image to Base64 nodejs` or `File to Base 64` if you
-          have an image file.
-    * function `fetchMessage(id)` - Fetches a message. Includes content and all parameters returned by Discord.
-        * id(string): ID of a message send by this webhook
-        * Returns `Message`
-    * function `delete()` - Deletes the webhook. Use with caution.
-    * function `resolveMessageID(messageID)` - Returns a MessageObject of a Message-ID
-        * messageID(string): ID of a message send by this webhook
-        * Returns `Message`
-        * NOTE: You can only get a `Message`-Object with to edit and delete the message - You can not (!) get the
-          content of it. Use `fetchMessage(id)` if you want to fetch content too.
-
-* Class: `Message(messageData, webhookurl)`
-    * `messageData` (object) has to have a value called `id` with the id of the message in it
-    * function `delete()` - Deletes the message
-        * Returns `Promise<boolean>` (true if everything went smoothly.)
-    * function `edit(content, embeds = [], allowedMentions = {})` - Edits the message
-        * content (string): Content of the message
-        * embeds (array, optional): Array
-          of [Embed-Objects](https://discord.com/developers/docs/resources/channel#embed-object)
-        * allowedMentions (object, optional):
-          A [Allowed-Mentions-Object](https://discord.com/developers/docs/resources/channel#allowed-mentions-object)
-        * components (array, optional): Array
-          of [message components](https://discord.com/developers/docs/interactions/message-components#component-object).
-          ⚠ This will only work, if your webhook is owned by an application.
-
-        * Returns `Promise<Message>`  (with all the values
-          from [here](https://discord.com/developers/docs/resources/channel#message-object))
+Please refer to the [online documentation](https://scderox.github.io/simple-discord-webhooks/). 
 
 # Questions or suggestions?
 

diff --git a/Webhook.js b/Webhook.js
@@ -1,13 +1,31 @@
 const centra = require('@aero/centra');
 const {Message} = require('./Message');
 
+/**
+ * Represents a webhook
+ */
 class Webhook {
+    /**
+     * Represents a new webhook
+     * @param {URL} url Webhook-URL
+     * @param {String} username Username of the webhook
+     * @param {URL} avatarUrl URL to a avatar
+     */
     constructor(url, username = null, avatarUrl = null) {
         this.url = url;
         this.username = username;
         this.avatarUrl = avatarUrl;
     }
 
+    /**
+     * Creates a new message as the webhook
+     * @param {String} content Content of this message
+     * @param {Array<Object>} embeds  Array of [Embed-Objects](https://discord.com/developers/docs/resources/channel#embed-object)
+     * @param {Object} allowedMentions  [Allowed-Mentions-Object](https://discord.com/developers/docs/resources/channel#allowed-mentions-object)
+     * @param {Boolean} tts If enabled, discord will read out the messages to everyone who hase this channel open
+     * @param {Array} components  [Message-Component-Object](https://discord.com/developers/docs/interactions/message-components#component-object). ⚠ This will only work, if your webhook is owned by an application.
+     * @return {Promise<Message>} New message
+     */
     async send(content, embeds = [], allowedMentions = {}, tts = false, components = []) {
         const res = await centra(this.url + '?wait=true', 'POST').body({
             content: content,
@@ -20,45 +38,53 @@ class Webhook {
         })
             .header('Content-Type', 'application/json')
             .send('form');
-        if (res.statusCode !== 200) {
-            console.error(`Something went wrong while sending while sending the webhook ${this.url}. Here is the answer from discord: `, res.body.toString());
-            return false;
-        }
+        if (res.statusCode !== 200) throw new Error(`Something went wrong while sending while sending the webhook ${this.url}. Here is the answer from discord: ` + res.body.toString())
         return new Message(JSON.parse(res.body.toString()), this.url);
     }
 
+    /**
+     * Edits this webhook object
+     * @param {String} name New username of the webhook
+     * @param {String} base64Avatar [Base64](https://en.wikipedia.org/wiki/Base64)-String of your image. If you don't know how to use this, please google Image to Base64 nodejs or File to Base 64 if you have an image file.
+     * @return {Promise<void>}
+     */
     async edit(name = null, base64Avatar = null) {
         const res = await centra(this.url, 'PATCH').body({
             name,
             avatar: base64Avatar ? `data:image/jpeg;base64,${base64Avatar}` : null
         })
             .header('Content-Type', 'application/json')
             .send('form');
-        if (res.statusCode !== 200) {
-            console.error(`Something went wrong while sending while sending the webhook ${this.url}. Here is the answer from discord: `, res.body.toString());
-            return false;
-        }
+        if (res.statusCode !== 200) throw new Error(`Something went wrong while sending while sending the webhook ${this.url}. Here is the answer from discord: `+ res.body.toString());
     }
 
+    /**
+     * Deletes this message
+     * @return {Promise}
+     */
     async delete() {
         const res = await centra(this.url, 'DELETE').body().send('form');
-        if (res.statusCode !== 204) {
-            console.error(`Something went wrong while sending while sending the webhook ${this.url}. Here is the answer from discord: `, res.body.toString());
-            return false;
-        }
+        if (res.statusCode !== 204) throw new Error(`Something went wrong while sending while sending the webhook ${this.url}. Here is the answer from discord: ` + res.body.toString());
     }
 
+    /**
+     * Fetches a message by ID (including content)
+     * @param {String} id ID of the message
+     * @return {Promise<Message>} Message
+     */
     async fetchMessage(id) {
         const res = await centra(this.url + `/messages/${id}`, 'GET')
             .send('form');
-        if (res.statusCode !== 200) {
-            console.error(`Something went wrong while sending while sending the webhook ${this.url}. Here is the answer from discord: `, res.body.toString());
-            return false;
-        }
+        if (res.statusCode !== 200) throw new Error(`Something went wrong while sending while sending the webhook ${this.url}. Here is the answer from discord: ` + res.body.toString());
         return new Message(JSON.parse(res.body.toString()), this.url)
     }
 
-    resolveMessageID(messageID) { // YOU CAN NOT GET ANY CONTENT OF A MESSAGE VIA THIS METHOD. YOU CAN *ONLY* USE THIS TO EDIT / DELETE ALREADY SEND MESSAGES
+    /**
+     * Resolves a message by ID (will not include any content of this message. Only use this if you want to edit or delate already send messages without having to fetch the message again
+     * @param messageID
+     * @return {Message}
+     */
+    resolveMessageID(messageID) {
         return new Message({id: messageID}, this.url);
     }
 }

diff --git a/jsdoc.conf.json b/jsdoc.conf.json
@@ -0,0 +1,28 @@
+{
+  "templates": {
+    "meta": {
+      "title": "simple-discord-webhooks Documentation"
+    },
+    "default": {
+      "includeDate": false
+    },
+    "applicationName": "simple-discord-webhooks"
+  },
+  "source": {
+    "include": [
+      "."
+    ],
+    "includePattern": ".+\\.js(doc|x)?$",
+    "excludePattern": "(node_modules|docs)"
+  },
+  "plugins": [
+    "plugins/markdown"
+  ],
+  "opts": {
+    "encoding": "utf8",
+    "destination": "./docs",
+    "recurse": true,
+    "readme": "./README.md",
+    "template": "./node_modules/@pixi/jsdoc-template"
+  }
+}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		patreon: scnetwork
		custom: [ 'https://bunq.me/scderox', 'https://paypal.me/therealscderox' ]