Add JSDoc to server/notification-providers/*

Signed-off-by: Matthew Nickson <mnickson@sidingsmedia.com>

server/notification-providers/aliyun-sms.js

@@ -37,6 +37,12 @@ class AliyunSMS extends NotificationProvider {
         }
     }
 
+    /**
+     * Send the SMS notification
+     * @param {BeanModel} notification Notification details
+     * @param {string} msgbody Message template
+     * @returns {boolean} True if successful else false
+     */
     async sendSms(notification, msgbody) {
         let params = {
             PhoneNumbers: notification.phonenumber,
@@ -70,7 +76,12 @@ class AliyunSMS extends NotificationProvider {
         return false;
     }
 
-    /** Aliyun request sign */
+    /**
+     * Aliyun request sign
+     * @param {Object} param Parameters object to sign
+     * @param {string} AccessKeySecret Secret key to sign parameters with
+     * @returns {string}
+     */
     sign(param, AccessKeySecret) {
         let param2 = {};
         let data = [];
@@ -93,6 +104,11 @@ class AliyunSMS extends NotificationProvider {
             .digest("base64");
     }
 
+    /**
+     * Convert status constant to string
+     * @param {const} status The status constant
+     * @returns {string}
+     */
     statusToString(status) {
         switch (status) {
             case DOWN:

server/notification-providers/bark.js

@@ -49,7 +49,12 @@ class Bark extends NotificationProvider {
         }
     }
 
-    // add additional parameter for better on device styles (iOS 15 optimized)
+    /**
+     * Add additional parameter for better on device styles (iOS 15
+     * optimized)
+     * @param {string} postUrl URL to append parameters to
+     * @returns {string}
+     */
     appendAdditionalParameters(postUrl) {
         // grouping all our notifications
         postUrl += "?group=" + barkNotificationGroup;
@@ -60,7 +65,11 @@ class Bark extends NotificationProvider {
         return postUrl;
     }
 
-    // thrown if failed to check result, result code should be in range 2xx
+    /**
+     * Check if result is successful
+     * @param {Object} result Axios response object
+     * @throws {Error} The status code is not in range 2xx
+     */
     checkResult(result) {
         if (result.status == null) {
             throw new Error("Bark notification failed with invalid response!");
@@ -70,6 +79,13 @@ class Bark extends NotificationProvider {
         }
     }
 
+    /**
+     * Send the message
+     * @param {string} title Message title
+     * @param {string} subtitle Message
+     * @param {string} endpoint Endpoint to send request to
+     * @returns {string}
+     */
     async postNotification(title, subtitle, endpoint) {
         // url encode title and subtitle
         title = encodeURIComponent(title);

server/notification-providers/dingding.js

@@ -37,6 +37,12 @@ class DingDing extends NotificationProvider {
         }
     }
 
+    /**
+     * Send message to DingDing
+     * @param {BeanModel} notification
+     * @param {Object} params Parameters of message
+     * @returns {boolean} True if successful else false
+     */
     async sendToDingDing(notification, params) {
         let timestamp = Date.now();
 
@@ -56,7 +62,12 @@ class DingDing extends NotificationProvider {
         return false;
     }
 
-    /** DingDing sign */
+    /**
+     * DingDing sign
+     * @param {Date} timestamp Timestamp of message
+     * @param {string} secretKey Secret key to sign data with
+     * @returns {string}
+     */
     sign(timestamp, secretKey) {
         return Crypto
             .createHmac("sha256", Buffer.from(secretKey, "utf8"))
@@ -64,7 +75,13 @@ class DingDing extends NotificationProvider {
             .digest("base64");
     }
 
+    /**
+     * Convert status constant to string
+     * @param {const} status The status constant
+     * @returns {string}
+     */
     statusToString(status) {
+        // TODO: Move to notification-provider.js to avoid repetition in classes
         switch (status) {
             case DOWN:
                 return "DOWN";

server/notification-providers/notification-provider.js

@@ -7,17 +7,23 @@ class NotificationProvider {
     name = undefined;
 
     /**
-     * @param notification : BeanModel
-     * @param msg : string General Message
-     * @param monitorJSON : object Monitor details (For Up/Down only)
-     * @param heartbeatJSON : object Heartbeat details (For Up/Down only)
+     * Send a notification
+     * @param {BeanModel} notification
+     * @param {string} msg General Message
+     * @param {?Object} monitorJSON Monitor details (For Up/Down only)
+     * @param {?Object} heartbeatJSON Heartbeat details (For Up/Down only)
      * @returns {Promise<string>} Return Successful Message
-     * Throw Error with fail msg
+     * @throws Error with fail msg
      */
     async send(notification, msg, monitorJSON = null, heartbeatJSON = null) {
         throw new Error("Have to override Notification.send(...)");
     }
 
+    /**
+     * Throws an error
+     * @param {any} error The error to throw
+     * @throws {any} The error specified
+     */
     throwGeneralAxiosError(error) {
         let msg = "Error: " + error + " ";
 

server/notification-providers/slack.js

@@ -10,6 +10,7 @@ class Slack extends NotificationProvider {
     /**
      * Deprecated property notification.slackbutton
      * Set it as primary base url if this is not yet set.
+     * @param {string} url The primary base URL to use
      */
     static async deprecateURL(url) {
         let currentPrimaryBaseURL = await setting("primaryBaseURL");

server/notification-providers/teams.js

@@ -5,6 +5,12 @@ const { DOWN, UP } = require("../../src/util");
 class Teams extends NotificationProvider {
     name = "teams";
 
+    /**
+     * Generate the message to send
+     * @param {const} status The status constant
+     * @param {string} monitorName Name of monitor
+     * @returns {string}
+     */
     _statusMessageFactory = (status, monitorName) => {
         if (status === DOWN) {
             return `🔴 Application [${monitorName}] went down`;
@@ -14,6 +20,11 @@ class Teams extends NotificationProvider {
         return "Notification";
     };
 
+    /**
+     * Select theme color to use based on status
+     * @param {const} status The status constant
+     * @returns {string} Selected color in hex RGB format
+     */
     _getThemeColor = (status) => {
         if (status === DOWN) {
             return "ff0000";
@@ -24,6 +35,14 @@ class Teams extends NotificationProvider {
         return "008cff";
     };
 
+    /**
+     * Generate payload for notification
+     * @param {const} status The status of the monitor
+     * @param {string} monitorMessage Message to send
+     * @param {string} monitorName Name of monitor affected
+     * @param {string} monitorUrl URL of monitor affected
+     * @returns {Object}
+     */
     _notificationPayloadFactory = ({
         status,
         monitorMessage,
@@ -74,10 +93,21 @@ class Teams extends NotificationProvider {
         };
     };
 
+    /**
+     * Send the notification
+     * @param {string} webhookUrl URL to send the request to
+     * @param {Object} payload Payload generated by _notificationPayloadFactory
+     */
     _sendNotification = async (webhookUrl, payload) => {
         await axios.post(webhookUrl, payload);
     };
 
+    /**
+     * Send a general notification
+     * @param {string} webhookUrl URL to send request to
+     * @param {string} msg Message to send
+     * @returns {Promise<void>}
+     */
     _handleGeneralNotification = (webhookUrl, msg) => {
         const payload = this._notificationPayloadFactory({
             monitorMessage: msg

server/notification-providers/wecom.js

@@ -24,6 +24,12 @@ class WeCom extends NotificationProvider {
         }
     }
 
+    /**
+     * Generate the message to send
+     * @param {Object} heartbeatJSON Heartbeat details (For Up/Down only)
+     * @param {string} msg General message
+     * @returns {Object}
+     */
     composeMessage(heartbeatJSON, msg) {
         let title;
         if (msg != null && heartbeatJSON != null && heartbeatJSON['status'] == UP) {