From 01c747b5d50ca67e22bbdc1a83946b28f1be73aa Mon Sep 17 00:00:00 2001 From: Aster Fialla Date: Fri, 13 Feb 2026 21:23:33 -0500 Subject: [PATCH] adding docstrings --- helpers/memberHelper.js | 100 ++++++++++++++++++++++++++++++++++----- helpers/messageHelper.js | 24 ++++++++-- helpers/webhookHelper.js | 25 +++++++++- 3 files changed, 130 insertions(+), 19 deletions(-) diff --git a/helpers/memberHelper.js b/helpers/memberHelper.js index 5c03858..5f035a2 100644 --- a/helpers/memberHelper.js +++ b/helpers/memberHelper.js @@ -1,7 +1,15 @@ import { db } from '../sequelize.js'; +import {enums} from "../enums.js"; const mh = {}; +/** + * Parses through the subcommands that come after "pf;member" and calls functions accordingly. + * + * @param {string} authorId - The author of the message + * @param {string[]} args - The message arguments + * @returns {string} A message. + */ mh.parseMemberCommand = async function(authorId, args){ console.log(authorId, args); if (!args) { @@ -11,24 +19,31 @@ mh.parseMemberCommand = async function(authorId, args){ case '--help': return enums.help.MEMBER; case 'add': - return await addNewMember(authorId, args); + return addNewMember(authorId, args); case 'remove': - return await removeMember(authorId, args); + return removeMember(authorId, args); } switch(args[1]) { case '--help': return enums.help.MEMBER; case 'displayname': - return await updateDisplayName(authorId, args); + return updateDisplayName(authorId, args); case 'proxy': - return await updateProxy(authorId, args); + return updateProxy(authorId, args); // case 'avatar': // return await set_avatar(authorId, args) default: - return await getMemberInfo(authorId, args); + return getMemberInfo(authorId, args[1]); } } +/** + * Adds a member, first checking that there is no member of that name associated with the author. + * + * @param {string} authorId - The author of the message + * @param {string[]} args - The message arguments + * @returns {string} A successful addition, or an error message. + */ async function addNewMember(authorId, args) { if (args[1] && args[1] === "--help" || !args[1]) { return enums.help.ADD; @@ -36,9 +51,7 @@ async function addNewMember(authorId, args) { const memberName = args[1]; const displayName = args[2]; - const member = await getMemberInfo(authorId, memberName); - if (member !== errorEnums.NO_MEMBER) { - return errorEnums.MEMBER_EXISTS; + const member = getMemberInfo(authorId, memberName); if (member !== enums.err.NO_MEMBER) { return enums.err.MEMBER_EXISTS; } @@ -56,6 +69,13 @@ async function addNewMember(authorId, args) { }) } +/** + * Updates the display name for a member. + * + * @param {string} authorId - The author of the message + * @param {string[]} args - The message arguments + * @returns {string} A successful update, or an error message. + */ async function updateDisplayName(authorId, args) { if (args[1] && args[1] === "--help" || !args[1]) { return enums.help.DISPLAYNAME; @@ -66,20 +86,26 @@ async function updateDisplayName(authorId, args) { const trimmed_name = displayName ? displayName.replaceAll(' ', '') : null; if (!displayName || trimmed_name === null ) { - let member = getMemberInfo(authorId, args); + let member = mh.getMemberByName(authorId, memberName); if (member.displayname) { return `Display name for ${memberName} is: ${member.displayname}.`; } return `Display name ${enums.err.NO_VALUE}` } - else if (displayName.count > 32) { - return errorEnums.DISPLAY_NAME_TOO_LONG; + else if (displayName.length > 32) { return enums.err.DISPLAY_NAME_TOO_LONG; } console.log(displayName); - return await updateMember(authorId, args); + return updateMember(authorId, args); } +/** + * Updates the proxy for a member, first checking that no other members attached to the author have the tag. + * + * @param {string} authorId - The author of the message + * @param {string[]} args - The message arguments + * @returns {string} A successful update, or an error message. + */ async function updateProxy(authorId, args) { if (args[1] && args[1] === "--help" || !args[1]) { return enums.help.PROXY; @@ -96,9 +122,16 @@ async function updateProxy(authorId, args) { if (proxyExists) { return enums.err.PROXY_EXISTS; } - return await updateMember(authorId, args); + return updateMember(authorId, args); } +/** + * Removes a member. + * + * @param {string} authorId - The author of the message + * @param {string[]} args - The message arguments + * @returns {string} A successful removal, or an error message. + */ async function removeMember(authorId, args) { if (args[1] && args[1] === "--help") { return enums.help.REMOVE; @@ -116,6 +149,14 @@ async function removeMember(authorId, args) { } /* non-commands */ + +/** + * Updates a member's fields in the database. + * + * @param {string} authorId - The author of the message + * @param {string[]} args - The message arguments + * @returns {string} A successful update, or an error message. + */ async function updateMember(authorId, args) { const memberName = args[0]; const columnName = args[1]; @@ -127,6 +168,13 @@ async function updateMember(authorId, args) { }); } +/** + * Gets the details for a member. + * + * @param {string} authorId - The author of the message + * @param {string} memberName - The message arguments + * @returns {string} The member's info, or an error message. + */ async function getMemberInfo(authorId, memberName) { let member = await db.members.findOne({ where: { name: memberName, userid: authorId } }); if (member) { @@ -139,12 +187,38 @@ async function getMemberInfo(authorId, memberName) { return enums.err.NO_MEMBER; } +/** + * Gets a member based on the author and proxy tag. + * + * @param {string} authorId - The author of the message. + * @param {string} name - The member's name. + * @returns {model | string} The member object, or an error message. + */ +mh.getMemberByName = async function(authorId, name) { + return await db.members.findOne({ where: { userid: authorId, name: name } }).catch(e => { + return `${enums.err.NO_MEMBER}: ${e.message}`; + }); +} + +/** + * Gets a member based on the author and proxy tag. + * + * @param {string} authorId - The author of the message + * @param {string} proxy - The proxy tag + * @returns {model | string} The member object, or an error message. + */ mh.getMemberByProxy = async function(authorId, proxy) { return await db.members.findOne({ where: { userid: authorId, proxy: proxy } }).catch(e => { return `${enums.err.NO_MEMBER}: ${e.message}`; }); } +/** + * Gets all members belonging to the author. + * + * @param {string} authorId - The author of the message + * @returns {model[] | string} The member object, or an error message. + */ mh.getMembersByAuthor = async function(authorId) { return await db.members.findAll({ where: { userid: authorId } }).catch(e => { // I have no idea how this could possibly happen but better safe than sorry diff --git a/helpers/messageHelper.js b/helpers/messageHelper.js index 0d47697..08700ce 100644 --- a/helpers/messageHelper.js +++ b/helpers/messageHelper.js @@ -4,9 +4,16 @@ const msgh = {}; msgh.prefix = "pf;" -msgh.parseCommandArgs = function(text, command_name) { - const message = text.slice(msgh.prefix.length + command_name.length).trim(); - // slices up message arguments including retaining quoted strings +/** + * Parses and slices up message arguments, retaining quoted strings. + * + * @param {string} text - The full message content. + * @param {string} commandName - The command name. + * @returns {string[]} An array of arguments. + */ +msgh.parseCommandArgs = function(text, commandName) { + const message = text.slice(msgh.prefix.length + commandName.length).trim(); + return message.match(/\\?.|^$/g).reduce((accumulator, chara) => { if (chara === '"') { // checks whether string is within quotes or not @@ -22,8 +29,15 @@ msgh.parseCommandArgs = function(text, command_name) { }, {array: ['']}).array // initial array with empty string for the reducer } -msgh.parseProxyTags = async function (author_id, text){ - const members = await memberHelper.getMembersByAuthor(author_id); +/** + * Parses proxy tags and sees if they match the tags of any member belonging to an author. + * + * @param {string} authorId - The author of the message. + * @param {string} text - The full message content. + * @returns {Object} The proxy message object. + */ +msgh.parseProxyTags = async function (authorId, text){ + const members = await memberHelper.getMembersByAuthor(authorId); const proxyMessage = {} members.forEach(member => { if (text.startsWith(member.proxy) && text.length > member.proxy.length) { diff --git a/helpers/webhookHelper.js b/helpers/webhookHelper.js index 32479dd..d3c52ff 100644 --- a/helpers/webhookHelper.js +++ b/helpers/webhookHelper.js @@ -1,14 +1,29 @@ const wh = {}; +/** + * Gets or creates a webhook. + * + * @param api - The discord.js API. + * @param {string} channelId - The channel the message was sent in. + * @returns {Object} A webhook object. + */ wh.getOrCreateWebhook = async function (api, channelId) { const name = 'PluralFlux Proxy Webhook'; let webhook = await getWebhook(api, channelId, name); - if (webhook === undefined) { + if (!webhook) { webhook = await api.channels.createWebhook(channelId, {name: name}); } return webhook; } +/** + * Gets an existing webhook. + * + * @param api - The discord.js API. + * @param {string} channelId - The channel the message was sent in. + * @param {string} name - The name of the webhook. + * @returns {Object} A webhook object. + */ async function getWebhook(api, channelId, name) { const allWebhooks = await api.channels.getWebhooks(channelId); if (allWebhooks.length === 0) { @@ -23,6 +38,14 @@ async function getWebhook(api, channelId, name) { return pf_webhook; } +/** + * Replaces a proxied message with a webhook using the member information. + * + * @param api - The discord.js API. + * @param data - The discord.js data. + * @param {string} text - The text to send via the webhook. + * @param {Object} member - A member object from the database. + */ wh.replaceMessage = async function (api, data, text, member) { if (text.length > 0) { const webhook = await wh.getOrCreateWebhook(api, data.channel_id);