From 158f4352efbc7645bed2bfc0325e4730d1816359 Mon Sep 17 00:00:00 2001 From: Sp3rick Date: Sun, 1 Sep 2024 19:44:04 +0200 Subject: [PATCH] Update 0.2.9 added LibreGroupHelp wiki for users and developers documentation better jsdocs on GHBot.js --- .github/workflows/ci.yml | 29 + CONFIG_DOCUMENTATION.md | 71 -- GHbot.js | 202 ++---- README.md | 105 +-- docs/.editorconfig | 12 + docs/assets/logo.png | Bin 0 -> 23011 bytes docs/documentation/GHBot.md | 938 ++++++++++++++++++++++++++ docs/documentation/TODO-List.md | 55 ++ docs/documentation/callbacks.md | 123 ++++ docs/documentation/commands.md | 184 +++++ docs/documentation/database.md | 74 ++ docs/documentation/editors.md | 99 +++ docs/documentation/events.md | 307 +++++++++ docs/documentation/index.md | 18 + docs/documentation/known-issues.md | 11 + docs/documentation/languages.md | 28 + docs/documentation/plugins.md | 34 + docs/index.md | 93 +++ docs/plugins/antiflood.md | 12 + docs/plugins/antispam.md | 12 + docs/plugins/captcha.md | 12 + docs/plugins/command-perms.md | 7 + docs/plugins/goodbye.md | 12 + docs/plugins/index.md | 5 + docs/plugins/message-maker.md | 90 +++ docs/plugins/pin.md | 7 + docs/plugins/promote.md | 7 + docs/plugins/punish.md | 7 + docs/plugins/roles-manager.md | 35 + docs/plugins/rules.md | 7 + docs/plugins/set-chat-based-punish.md | 17 + docs/plugins/settings.md | 7 + docs/plugins/warns.md | 12 + docs/plugins/welcome.md | 12 + docs/wiki/commands.md | 172 +++++ docs/wiki/configuration.md | 71 ++ docs/wiki/perms.md | 46 ++ docs/wiki/roles.md | 87 +++ documentation.md | 248 ------- mkdocs.yml | 80 +++ package.json | 3 + plugins.md | 439 ------------ runDocs.js | 24 + 43 files changed, 2835 insertions(+), 979 deletions(-) create mode 100644 .github/workflows/ci.yml delete mode 100644 CONFIG_DOCUMENTATION.md create mode 100644 docs/.editorconfig create mode 100644 docs/assets/logo.png create mode 100644 docs/documentation/GHBot.md create mode 100644 docs/documentation/TODO-List.md create mode 100644 docs/documentation/callbacks.md create mode 100644 docs/documentation/commands.md create mode 100644 docs/documentation/database.md create mode 100644 docs/documentation/editors.md create mode 100644 docs/documentation/events.md create mode 100644 docs/documentation/index.md create mode 100644 docs/documentation/known-issues.md create mode 100644 docs/documentation/languages.md create mode 100644 docs/documentation/plugins.md create mode 100644 docs/index.md create mode 100644 docs/plugins/antiflood.md create mode 100644 docs/plugins/antispam.md create mode 100644 docs/plugins/captcha.md create mode 100644 docs/plugins/command-perms.md create mode 100644 docs/plugins/goodbye.md create mode 100644 docs/plugins/index.md create mode 100644 docs/plugins/message-maker.md create mode 100644 docs/plugins/pin.md create mode 100644 docs/plugins/promote.md create mode 100644 docs/plugins/punish.md create mode 100644 docs/plugins/roles-manager.md create mode 100644 docs/plugins/rules.md create mode 100644 docs/plugins/set-chat-based-punish.md create mode 100644 docs/plugins/settings.md create mode 100644 docs/plugins/warns.md create mode 100644 docs/plugins/welcome.md create mode 100644 docs/wiki/commands.md create mode 100644 docs/wiki/configuration.md create mode 100644 docs/wiki/perms.md create mode 100644 docs/wiki/roles.md delete mode 100644 documentation.md create mode 100644 mkdocs.yml delete mode 100644 plugins.md create mode 100644 runDocs.js diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..91cb81d --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,29 @@ +name: ci +on: + push: + branches: + - master + - main +permissions: + contents: write +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Configure Git Credentials + run: | + git config user.name github-actions[bot] + git config user.email 41898282+github-actions[bot]@users.noreply.github.com + - uses: actions/setup-python@v5 + with: + python-version: 3.x + - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV + - uses: actions/cache@v4 + with: + key: mkdocs-material-${{ env.cache_id }} + path: .cache + restore-keys: | + mkdocs-material- + - run: pip install mkdocs-material + - run: mkdocs gh-deploy --force diff --git a/CONFIG_DOCUMENTATION.md b/CONFIG_DOCUMENTATION.md deleted file mode 100644 index cd5bf86..0000000 --- a/CONFIG_DOCUMENTATION.md +++ /dev/null @@ -1,71 +0,0 @@ - config.json documentation - -Essential settings - -botToken: - Your bot token that you can get from @BotFather - -botStaff: - Array of userId(String) considered bot staff - - -Privacy settings - -deleteChatDataAfterBotRemove: - If enabled all chat data (configurations included) will be deleted from bot database when you kick the bot from a group - -overwriteChatDataIfReAddedToGroup: - If enabled chat data and configurations will be regenerated if bot has been re-added to the group (similiar to deleteChatDataAfterBotRemove,) - -allowExternalApi: - Allow to gather additional data by varous online api's, that's may reveal the ip of your server, default to false - - -Other settings - -reserveLang: - Principal language for the bot, this will be used to overwrite other languages with incompleted translations, we advise to keep it unchanged or use a full implemented language - -saveDatabaseSeconds: - Number of seconds of how often loaded chats should be written on disk, useful to prevent data loss on crash - -saveTagResolverSeconds: - Number of seconds of how often tagResolver data should be saved on disk - -maxCallbackAge: - Maximum number of seconds a callback button should be old to be accepted by the bot, you can reduce this in case of incompatible callbacks after an update that cause crash - -preventSetUselessRoles: - Disallow from setting roles if it does not change the user status in the group - -chatWhitelist: - Array, if there are at least one element the bot will work only on this chat ids - -privateWhitelist: - Boolean, true if chat whitelist includes private chats, useless if chatWhitelist has no elements - -chatBlacklist: - Bot wont more handle requests of chat ids in this array - - -Plugin settings - -ANTIFLOOD_msgMin: - minimum allowed number of messages to triggher the antiflood - -ANTIFLOOD_msgMax: - maximum allowed number of messages to triggher the antiflood - -ANTIFLOOD_timeMin: - minimum allowed time in which N messages should be sent to triggher the antiflood - -ANTIFLOOD_timeMax: - maximum allowed time in which N messages should be sent to triggher the antiflood - -minWarns: - minimum allowed warns in settings - -maxWarns: - maximum allowed warns in settings - - diff --git a/GHbot.js b/GHbot.js index 3462db4..eb2af08 100644 --- a/GHbot.js +++ b/GHbot.js @@ -1,16 +1,14 @@ const TelegramBot = require("node-telegram-bot-api"); const { pushUserRequest } = require("./api/tg/SafeTelegram"); -/** - * @typedef {import("node-telegram-bot-api")} TelegramBot - */ //BASIC DECLARATIONS /** - * @typedef {Object} AnonTGUser - Descrizione di base dell'oggetto. + * @typedef {Object} AnonTGUser - Basic anonymized user object * @property {String|Number} id - userId */ + //PUNISH /** * @typedef {0|1|2|3|4} Punishment @@ -23,7 +21,7 @@ const { pushUserRequest } = require("./api/tg/SafeTelegram"); */ /** * @typedef {Object} LGHPunish antispam.js settings Object. - * @property {Punishment} punishment - Punishment to apply [0:off|1:warn|2:kick|3:mute|4:ban]. + * @property {Punishment} punishment - Punishment to apply [0:off/1:warn/2:kick/3:mute/4:ban]. * @property {Number|null} PTime - Available if punishment is set to warn/mute/ban, contains seconds of punishment. * @property {boolean|null} delete - True if deletion is enabled as side effect. */ @@ -42,46 +40,60 @@ const { pushUserRequest } = require("./api/tg/SafeTelegram"); * @property {LGHPunish} latin - Punish to apply for messages containing latin characters. */ + //TARGETUSER /** * @typedef {Object} TargetUser - Object that refers to a target user * @property {string|number} id - Telegram user Id * @property {string} name - Full LGH name identifier: "fullName [id]" * @property {LGHPerms} perms - LGHPerms with perms of target - * @property {TelegramBot.usersDir|false} user - If avaiable, target basic user object + * @property {TelegramBot.User|null} user - If avaiable, target basic user object */ +/** + * @enum {number} + * @description Permission status + * - 1: allowed + * - 0: neutral + * - -1: denied + */ +const PermissionStatus = { + ALLOWED: 1, + NEUTRAL: 0, + DENIED: -1, +}; + //PERMISSIONS /** * @typedef {Object} LGHPerms - LGHPerms Object. * @property {Array.} commands - Array of commands, if starts with "COMMAND_" means its to be translated, otherwise is the literal command. - * @property {1|0|-1} immune - Active if this user can't receive any punishment (kick/warn/mute/ban) [1/0/-1]. - * @property {1|0|-1} flood - Permission to flood messages [1/0/-1]. - * @property {1|0|-1} link - Permission to send links [1/0/-1]. - * @property {1|0|-1} tgLink - Permission to send telegram links/usernames [1/0/-1]. - * @property {1|0|-1} forward - Permission to forward messages from anywhere [1/0/-1]. - * @property {1|0|-1} quote - Permission to quote from anywhere [1/0/-1]. - * @property {1|0|-1} porn - Bypass porn/gore checks [1/0/-1]. - * @property {1|0|-1} night - Bypass any night mode limitation [1/0/-1]. - * @property {1|0|-1} media - Bypass any media limitation [1/0/-1]. - * @property {1|0|-1} alphabets - Bypass any alphabets characters limitations [1/0/-1]. - * @property {1|0|-1} words - Bypass banned words limitations [1/0/-1]. - * @property {1|0|-1} length - Bypass message length limitations [1/0/-1]. - * @property {1|0|-1} roles - Permission to change roles of lower level users [1/0/-1]. - * @property {1|0|-1} settings - Permission to change bot group settings [1/0/-1]. + * @property {PermissionStatus} immune - Active if this user can't receive any punishment (kick/warn/mute/ban) [1/0/-1]. + * @property {PermissionStatus} flood - Permission to flood messages [1/0/-1]. + * @property {PermissionStatus} link - Permission to send links [1/0/-1]. + * @property {PermissionStatus} tgLink - Permission to send telegram links/usernames [1/0/-1]. + * @property {PermissionStatus} forward - Permission to forward messages from anywhere [1/0/-1]. + * @property {PermissionStatus} quote - Permission to quote from anywhere [1/0/-1]. + * @property {PermissionStatus} porn - Bypass porn/gore checks [1/0/-1]. + * @property {PermissionStatus} night - Bypass any night mode limitation [1/0/-1]. + * @property {PermissionStatus} media - Bypass any media limitation [1/0/-1]. + * @property {PermissionStatus} alphabets - Bypass any alphabets characters limitations [1/0/-1]. + * @property {PermissionStatus} words - Bypass banned words limitations [1/0/-1]. + * @property {PermissionStatus} length - Bypass message length limitations [1/0/-1]. + * @property {PermissionStatus} roles - Permission to change roles of lower level users [1/0/-1]. + * @property {PermissionStatus} settings - Permission to change bot group settings [1/0/-1]. */ //MESSAGEMAKER /** - * @typedef {Object} simpleMedia - object with data about an user in a group - * @property {String|false} type - Type of media (audio, photo, video, video_note, animation, sticker, document) or false + * @typedef {Object} simpleMedia + * @property {String|null} type - Type of media (audio, photo, video, video_note, animation, sticker, document) or false * @property {String} fileId - media fileId or false * @property {Object} options - additional options for TelegramBot */ /** - * @typedef {Object} customMessage - object with data about an user in a group + * @typedef {Object} customMessage - object of MessageMaker * @property {String} text - Text of messsage * @property {Array.} entities - Telegram entities of text * @property {Array.} roles - array user roles, string for pre-made roles, number for custom roles (user-made) @@ -91,14 +103,19 @@ const { pushUserRequest } = require("./api/tg/SafeTelegram"); * @property {Array.} buttonsParsed - already parsed buttons ready to use for inline_keyboard */ + //CUSTOM CHAT DECLARATIONS /** - * @typedef {TelegramBot.ChatAdministratorRights & {user: AnonTGUser} & {status: TelegramBot.ChatMemberStatus}} LGHAdmin + * @typedef {object} LGHAdminAdds + * @property {AnonTGUser} user - Basic anonymized user object + * @property {TelegramBot.ChatMemberStatus} status + */ +/** + * @typedef {TelegramBot.ChatAdministratorRights | LGHAdminAdds} LGHAdmin */ /** * @typedef {Array} LGHAdminList */ - /** * @typedef {Object} userStatus - object with data about an user in a group * @property {Number} firtJoin - Unix number of first user join time in seconds, false if unknown (managed by welcome.js) @@ -106,9 +123,8 @@ const { pushUserRequest } = require("./api/tg/SafeTelegram"); * @property {LGHPerms} adminPerms - LGHPerms object for user permissions if admin * @property {Array.} roles - array user roles, string for pre-made roles, number for custom roles (user-made) * @property {String|undefined} title - user administrator title - * @property {String|false} waitingReply - string with callback data hirarchy if bot is expecting a message from user on group + * @property {String|null} waitingReply - string with callback data hirarchy if bot is expecting a message from user on group */ - /** * @typedef {Object} LGHRole - if pre-made role (string key) only users object should be used * @property {String|null} name - role name @@ -118,6 +134,7 @@ const { pushUserRequest } = require("./api/tg/SafeTelegram"); * @property {Array.} users - array of userId in this role */ + //PLUGINS DECLARATIONS //warns /** @@ -125,7 +142,7 @@ const { pushUserRequest } = require("./api/tg/SafeTelegram"); * @property {Object.} timed - ([userId]: [endTime, endTime, endTime]) contains necerray data to revoke scheduled warns when time is over * @property {Object.} count - ([userId]: number) countains count of warns for each user * @property {Number} limit - number of warns after wich should be applyed a punishment - * @property {2|3|4} punishment - punishment when limit is hit [2:kick|3:mute|4:ban] + * @property {2|3|4} punishment - punishment when limit is hit [2:kick/3:mute/4:ban] * @property {Number|null} PTime - avaiable if punishment is set to warn/mute/ban, contains seconds of punishment */ @@ -155,7 +172,7 @@ const { pushUserRequest } = require("./api/tg/SafeTelegram"); * @typedef {Object} LGHSpamTgLinksAdds - antispam.js settings Object additional items. * @property {Boolean} usernames - True if usernames should be considered as spam. * @property {Boolean} bots - True if bots should be considered as spam. - * @property {Array} exceptions - Array of Telegram exceptions, may contain "Name:Id", "Name:|hidden" (for hidden users), or t.me link, or @username, "Name" + * @property {Array} exceptions - Array of Telegram exceptions, may contain "Name:Id", `Name:|hidden` (for hidden users), or t.me link, or @username, "Name" */ /** * @typedef {LGHSpamTgLinksAdds & LGHPunish} LGHSpamTgLinks - antispam.js settings about Telegram Links Object. @@ -200,7 +217,7 @@ const { pushUserRequest } = require("./api/tg/SafeTelegram"); * @property {Number} time - Time limit to solve the captcha * @property {boolean} once - True if should be sent only at first user join (from welcome.js) (default false). * @property {boolean} fails - True if captcha should notify on group that someone failed the captcha (default false). - * @property {Punishment} punishment - Punishment to apply [1:warn|2:kick|3:mute|4:ban]. + * @property {Punishment} punishment - Punishment to apply [1:warn/2:kick/3:mute/4:ban]. * @property {Number} PTime - Available if punishment is set to warn/mute/ban, contains seconds of punishment. */ @@ -259,8 +276,8 @@ const { pushUserRequest } = require("./api/tg/SafeTelegram"); * @property {LGHAdminList|null} admins - array with known admins objects (user data anonymized) * @property {String|null} lang - current chat lang * @property {String|null} currency - currency of chat, default to USD - * @property {string|false} link - group access link - * @property {Boolean} isGroup - temporary item, result of (chat.type == "supergroup" || chat.type == "group") + * @property {string|null} link - group access link + * @property {Boolean} isGroup - temporary item, result of `(chat.type == "supergroup" || chat.type == "group")` * @property {Object.|null} users - Object-IdName based data about every user in the group (ex. users[643547] access data of userId 643547) * @property {Object.|null} roles - data about a specific role, full role Object if it's a custom role (key with a number) * @property {LGHPerms} basePerms - base permissions applyed to every user @@ -275,7 +292,6 @@ const { pushUserRequest } = require("./api/tg/SafeTelegram"); * @property {LGHAlphabetBasedPunish|null} alphabets - alphabets.js plugin related data * @property {LGHMedia|null} media - media.js plugin related data */ - /** * @typedef {TelegramBot.Chat & CustomChat} LGHChat - Full LGH chat object given by LGHBot events, custom items avaiable if working about a group */ @@ -295,7 +311,7 @@ testObject() * @property {LGHPerms|null} perms - temporary object with summary of user permissions * @property {String} lang - current user lang * @property {String} waitingReply - set to true if the bot is expecting a message from the user - + */ /** * @typedef {TelegramBot.User & CustomUser} LGHUser - Custom chat object given by LGHBot events, custom items avaiable if working about a group */ @@ -312,21 +328,18 @@ testObject() * @property {(string|boolean)} args - The arguments of the command (optional). * @property {(Array.|boolean)} splitArgs - The split arguments of the command (optional). */ - /** * @typedef {Object} CustomCommand - Additional items to command for LGH - * @property {TargetUser|false} target - Optional temporary object with data about a target LGH user in the command, false if no target found + * @property {TargetUser|null} target - Optional temporary object with data about a target LGH user in the command, false if no target found */ - /** * @typedef {Object} CustomMessage * @property {LGHChat} chat - Always original chat object where the message is coming from * @property {ParsedCommand & CustomCommand} command - result of message text parsed with parseCommand() - * @property {TargetUser|false} target - Optional temporary object with data about a command target - * @property {string|false} waitingReply - Optional temporary object with waitingReply data for the selected chat - * @property {TargetUser|false} waitingReplyTarget - Optional temporary object with data about a target LGH user, false if no target found + * @property {TargetUser|null} target - Optional temporary object with data about a command target + * @property {string|null} waitingReply - Optional temporary object with waitingReply data for the selected chat + * @property {TargetUser|null} waitingReplyTarget - Optional temporary object with data about a target LGH user, false if no target found */ - /** * @typedef {TelegramBot.Message & CustomMessage} LGHMessage - Custom chat object given by LGHBot events, custom items avaiable if working about a group */ @@ -338,98 +351,29 @@ testObject() * @property {LGHChat} chat - Always original chat object where the callback is coming from * @property {TargetUser} target - Optional temporary object with data about a target LGH user in the command, false if no target found */ - /** * @typedef {TelegramBot.CallbackQuery & CustomCallback} LGHCallback - Custom callback object given by LGHBot events, custom items may be avaiable */ //DATABASE -/** - * @typedef {Function} AddChatFunction - * @param {LGHChat} chat - The chat object to add. - * @returns {Boolean} True if the chat was successfully added, otherwise false. - */ - -/** - * @typedef {Function} DeleteChatFunction - * @param {TelegramBot.ChatId} chatId - The ID of the chat to delete. - * @returns {Boolean} True if the chat was successfully deleted, otherwise false. - */ - -/** - * @typedef {Function} ExistChatFunction - * @param {TelegramBot.ChatId} chatId - The ID of the chat to check. - * @returns {Boolean} True if the chat exists in the database, otherwise false. - */ - -/** - * @typedef {Function} GetChatFunction - * @param {TelegramBot.ChatId} chatId - The ID of the chat to retrieve. - * @returns {LGHChat|false} The retrieved chat object if found, otherwise false. - */ - -/** - * @typedef {Function} UpdateChatFunction - * @param {LGHChat} chat - The updated chat object. - * @returns {Boolean} True if the chat was successfully updated, otherwise false. - */ - -/** - * @typedef {Function} SaveChatFunction - * @param {TelegramBot.ChatId} chatId - The ID of the chat to save. - * @returns {Boolean} True if the chat was successfully saved, otherwise false. - */ - /** * @typedef {Object} chatsDatabase - Object containing chat-related database functions. - * @property {AddChatFunction} add - Function to add a new chat to the database. - * @property {DeleteChatFunction} delete - Function to delete a chat from the database. - * @property {ExistChatFunction} exhist - Function to check if a chat exhists in the database. - * @property {GetChatFunction} get - Function to retrieve a chat from the database. - * @property {UpdateChatFunction} update - Function to update a chat in the database. - * @property {SaveChatFunction} save - Function to save a chat to the database. + * @property {function(TelegramBot.Chat): boolean} add - Function to add a new chat to the database. ------------------------------------ `function(TelegramBot.Chat): boolean` + * @property {function(TelegramBot.ChatId): boolean} delete - Function to delete a chat from the database. ------------------------------------ `function(TelegramBot.ChatId): boolean` + * @property {function(TelegramBot.ChatId): boolean} exhist - Function to check if a chat exhists in the database. ------------------------------------ `function(TelegramBot.ChatId): boolean` + * @property {function(TelegramBot.ChatId): LGHChat} get - Function to retrieve a chat from the database. ------------------------------------ `function(LGHChat): boolean` + * @property {function(LGHChat): boolean} update - Function to update a chat in the database. ------------------------------------ `function(LGHChat): boolean` + * @property {function(TelegramBot.ChatId): boolean} save - Function to save a chat to the database. ------------------------------------ `function(TelegramBot.ChatId): boolean` */ - -/** - * @typedef {Function} AddUserFunction - * @param {LGHUser} user - The user object to add. - * @returns {Boolean} Result of adding a user to the database. - */ - -/** - * @typedef {Function} DeleteUserFunction - * @param {TelegramBot.ChatId} userId - The ID of the user to delete. - * @returns {Boolean} Result of deleting a user from the database. - */ - -/** - * @typedef {Function} ExistUserFunction - * @param {TelegramBot.ChatId} userId - The ID of the user to check. - * @returns {Boolean} Indicates whether the user exists in the database. - */ - -/** - * @typedef {Function} GetUserFunction - * @param {TelegramBot.ChatId} userId - The ID of the user to retrieve. - * @returns {LGHUser} Data retrieved for the user from the database. - */ - -/** - * @typedef {Function} UpdateUserFunction - * @param {LGHUser} user - The updated user object. - * @returns {boolean} True if the user was successfully updated, otherwise false. - */ - /** * @typedef {Object} usersDatabase - Object containing user-related database functions. - * @property {Function} add - Function to add a new user to the database. - * @property {Function} delete - Function to delete a user from the database. - * @property {Function} exhist - Function to check if a user exhists in the database. - * @property {Function} get - Function to retrieve a user from the database. - * @property {Function} update - Function to update a user in the database. + * @property {function(TelegramBot.User): boolean} add - Function to add a new user to the database. ------------------------------------ `function(TelegramBot.User): boolean` + * @property {function(TelegramBot.ChatId): boolean} delete - Function to delete a user from the database. ------------------------------------ `function(TelegramBot.ChatId): boolean` + * @property {function(TelegramBot.ChatId): boolean} exhist - Function to check if a user exhists in the database. ------------------------------------ `function(TelegramBot.ChatId): boolean` + * @property {function(TelegramBot.ChatId): LGHUser} get - Function to retrieve a user from the database. ------------------------------------ `function(TelegramBot.ChatId): LGHUser` + * @property {function(LGHUser): boolean} update - Function to update a user in the database. ------------------------------------ `function(LGHUser): boolean` */ - /** * @typedef {Object} LGHDatabase - Type returned by the getDatabase function. * @property {string} innerDir - Location where the database folder should be placed (and/or generated). @@ -445,9 +389,9 @@ testObject() //TEMPLATE DECLARATION /** * @typedef {Object} LibreGHelp - * @property {TelegramBot} GHbot - Test - * @property {TelegramBot} TGbot - Test - * @property {LGHDatabase} db - Test + * @property {LGHInterface} GHbot - Public interface for LGH Functions + * @property {TelegramBot} TGbot - Raw telegram bot api + * @property {LGHDatabase} db - Database interface */ /** @@ -455,11 +399,11 @@ testObject() * @classdesc * @param {LibreGHelp} LibreGHelp - Libre Group Help telegram bot handler */ -class main { +class LGHInterface { constructor(LibreGHelp) { /** - * @type {TelegramBot} + * @type {LGHInterface} */ this.GHbot = LibreGHelp.GHbot; @@ -483,7 +427,7 @@ class main { /** * LGHbot message event handler - * @param {(arg1: LGHMessage, arg2: LGHChat, arg3: LGHUser) => void} handler - handler function + * @param {function(LGHMessage, LGHChat, LGHUser): void} handler - handler function */ onMessage(handler) { this.GHbot.on("message", handler); @@ -491,7 +435,7 @@ class main { /** * LGHbot callback event handler - * @param {(arg1: LGHCallback, arg2: LGHChat, arg3: LGHUser) => void} handler - handler function + * @param {function(LGHCallback, LGHChat, LGHUser): void} handler - handler function */ onCallback(handler) { this.GHbot.on("callback_query", handler); @@ -652,4 +596,4 @@ class main { } )} } -module.exports = main; +module.exports = LGHInterface; diff --git a/README.md b/README.md index 27b2837..8b67ce9 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -## LibreGroupHelp +# LibreGroupHelp Open-Source re-creation of telegram group manager Group Help in NodeJS based on [node-telegram-api](https://github.com/yagop/node-telegram-bot-api). @@ -6,39 +6,23 @@ An official instance of bot is running on [@LibreGroupHelpBot](https://t.me/Libr ## Installation: -```bash -npm install -``` +Be sure to have installed a recent version of [NodeJS](https://nodejs.org/) -Set your bot token on config.js, look at [config documentation](https://github.com/Sp3rick/GroupHelp/blob/main/CONFIG_DOCUMENTATION.md). +Verify NodeJS installation with `node -v` -Run with: -```bash -node index.js -``` +Set your bot token using configuration file, look at [config documentation](configuration.md). -Installation trubleshooting: +Open a terminal inside LibreGroupHelp folder and run this commands -if you have problems with node-telegram-bot-api installation try this command url based: ```bash -npm i https://github.com/yagop/node-telegram-bot-api +npm install ``` -and if needed install other packages manually: +Now you should be ready to run LibreGroupHelp using: ```bash -npm i chrono-node +node index.js ``` -## Contribute - -Useful links to contribute: - -[documentation.md](https://github.com/Sp3rick/GroupHelp/blob/main/documentation.md). - -[Create a plugin](https://github.com/Sp3rick/GroupHelp/blob/main/plugins.md). - -[TODO (good first issue)](https://github.com/Sp3rick/GroupHelp/contribute). - ## What is done @@ -97,75 +81,12 @@ Useful links to contribute: ``` ## Updating -To update the bot you need to backup ./database folder and ./config.json only, then repeat installation process and paste there the old database and config.json, you may need to add some config.json parameters manually - - -## Our TODO List: - --short term: - - allow to edit single user perms - commands help panel - --medium term: - - allow on /perms to change user perms and roles, +add it in a button for /info or when a role is set (/free /mod etc..), +ask double confirm to give an user the "settings" and "roles" permission - support for anonymous admins - allow to customize /staff allowing to set roles to hide - create a privacy setting where users can ask to esclude themself from tagResolver and replace his's first name in database with "Anonymous" - allow to disable tagResolver log on group settings - allow to mute only media, or specific media type or extras - create a privacy option to allow a user deleting his data from the bot - custom roles - optimize database.get, .update and .save to store in temporal array most used users - implement time zone setting +implement it in /info - --long term: - - add log channel - chatIds anonymization on database - compress chats data stored on database - support all group help functions and more (+anti-sheduled messages[msg.is_from_offline], ) - allow bot clone bot when user give a token - add optionally an userbot (when active implement in tagResolver.js) - --other things: - - implement direct private settings with /*settings - add a /commands command to help user to know bot commands, admin commands, and custom-group commands if avaiable - a check system to drop wrong formatted cb.data and waitingReply - allow to see perms calculation trough user perms, then roles by priority, then base group perms, going from left to right (or opposite) - add something to allow a group admin to identify all users with additional bot perms - ?add an automatic leveling system for admins? (maybe?) - add photo preview-mode in MessageMaker.js - allow to warn only usersIds who exhist on telegram, it can be checked if applyng a restriction returns true - add config to allow/disallow adding bot from non-admin users - ?identify reply_parameters and add everytime allow_sending_without_reply? (GHBot.js) - /geturl, by replying to a message (via reply) and writing this command, you receive the link that refers directly to that message. - /inactives [days] sends in private chat the list of users who have not sent a message in the last [days], with the possibility of punish them. - /pin [message] - sends the message through the Bot and pins it. - /editpin [message] - edits the current pinned message (if sent from the Bot). - /delpin - removes the pinned message. - /repin - removes and pins again the current pinned message, with notification! - /pinned - refers to the current pinned message. - /list - sends in private chat the list of users of the group with the number of messages sent by them. - /list roles - sends in private chat the list of all the special roles assigned to users - /graphic - sends a graph showing the trend of the group members. - /trend - sends the group's growth statistics. - /logdel - deletes the selected message and sends it to the Log Channel - /send - permits to send a post through the Bot with parse mode support - -## Known possible bugs: --sometimes db.chats.update in plugins may be not used at all because you can still edit the global object cause to reference, not using it may cause some issue. +if global reference get cleared too early code may try to access and inexistent variable - --cleanHTML() may be not applyed in some text where it should, and nothing assure that it's 100% able to clean everything needed for telegram api - --if you add a new permission on userPerms object, every userPerms object should be updated adding that, otherwise this may cause incorrect result in sumUserPerms - --in some unkown cases you may get stuck in exceptions menu and SafeGram.js will block any user request due too high accumulated volume of something pending - --permissions setup on first bot adding to groups is not the same as using /reload that's more complete +To update LibreGroupHelp you need to backup ./database folder and ./config.json, then repeat installation process and paste there again both file and folder, you may need to add some config.json parameters manually if has been added + +## Contribute + +[Documentation](../documentation/) is the section you are looking for if you want to contribute to LibreGroupHelp ## Ask a question diff --git a/docs/.editorconfig b/docs/.editorconfig new file mode 100644 index 0000000..ebe51d3 --- /dev/null +++ b/docs/.editorconfig @@ -0,0 +1,12 @@ +# EditorConfig is awesome: https://EditorConfig.org + +# top-most EditorConfig file +root = true + +[*] +indent_style = space +indent_size = 2 +end_of_line = lf +charset = utf-8 +trim_trailing_whitespace = false +insert_final_newline = false \ No newline at end of file diff --git a/docs/assets/logo.png b/docs/assets/logo.png new file mode 100644 index 0000000000000000000000000000000000000000..76ad85c66dec592e043a38ea0e45ee8be9cc7de6 GIT binary patch literal 23011 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 literal 0 HcmV?d00001 diff --git a/docs/documentation/GHBot.md b/docs/documentation/GHBot.md new file mode 100644 index 0000000..546478a --- /dev/null +++ b/docs/documentation/GHBot.md @@ -0,0 +1,938 @@ +## TelegramBot api + +You can finnd documentation about TelegramBot Objects on [telegram-bot-api](https://github.com/yagop/node-telegram-bot-api/blob/master/doc/api.md) github + +--- + +The down below lines are generated with [jsdoc2md](https://github.com/jsdoc2md/jsdoc-to-markdown) + + +## Classes + +
+
LGHInterface
+
+
+ +## Functions + +
+
testObject() ⇒ LGHChat
+
+
+ +## Typedefs + +
+
AnonTGUser : Object
+

Basic anonymized user object

+
+
Punishment : 0 | 1 | 2 | 3 | 4
+

Punishment to apply

+
    +
  • 0: off
    • +
  • 1: warn
    • +
  • 2: kick
    • +
  • 3: mute
    • +
  • 4: ban
    • +
+
+
LGHPunish : Object
+

antispam.js settings Object.

+
+
LGHChatBasedPunish : Object
+

Object to reresent different punish settings for more chat types

+
+
LGHAlphabetBasedPunish : Object
+

Object to reresent different punish settings for messages containing various Alphabets

+
+
TargetUser : Object
+

Object that refers to a target user

+
+
LGHPerms : Object
+

LGHPerms Object.

+
+
simpleMedia : Object
+
+
customMessage : Object
+

object of MessageMaker

+
+
LGHAdminAdds : object
+
+
LGHAdmin : TelegramBot.ChatAdministratorRights | LGHAdminAdds
+
+
LGHAdminList : Array.<LGHAdmin>
+
+
userStatus : Object
+

object with data about an user in a group

+
+
LGHRole : Object
+

if pre-made role (string key) only users object should be used

+
+
LGHWarns : Object
+

warns.js plugin related data

+
+
LGHWelcome : Object
+

welcome.js settings Object.

+
+
LGHFloodAdds : Object
+

antiflood.js settings additional Object elements.

+
+
LGHFlood : LGHFloodAdds | LGHPunish
+

antiflood.js settings Object.

+
+
LGHSpamTgLinksAdds : Object
+

antispam.js settings Object additional items.

+
+
LGHSpamTgLinks : LGHSpamTgLinksAdds | LGHPunish
+

antispam.js settings about Telegram Links Object.

+
+
LGHSpamLinksAdds : Object
+

antispam.js spam links Object additional items.

+
+
LGHSpamLinks : LGHSpamLinksAdds | LGHPunish
+

antispam.js settings about Links Object.

+
+
LGHSpamForward : LGHChatBasedPunish
+

antispam.js settings about foward.

+
+
LGHSpamQuote : LGHChatBasedPunish
+

antispam.js settings about quote.

+
+
LGHSpam : Object
+

antispam.js settings Object.

+
+
LGHGoodbye : Object
+

goodbye.js settings

+
+
LGHCaptcha : Object
+

captcha.js settings

+
+
LGHMedia : Object
+

media.js settings, if LGHPunish is disabled the object will be deleted (undefinied)

+
+
CustomChat : Object
+

Additional chat elements for chat object by LibreGroupHelp

+
+
LGHChat : TelegramBot.Chat | CustomChat
+

Full LGH chat object given by LGHBot events, custom items avaiable if working about a group

+
+
CustomUser : Object
+
+
LGHUser : TelegramBot.User | CustomUser
+

Custom chat object given by LGHBot events, custom items avaiable if working about a group

+
+
ParsedCommand : Object
+

ParsedCommand Object.

+
+
CustomCommand : Object
+

Additional items to command for LGH

+
+
CustomMessage : Object
+
+
LGHMessage : TelegramBot.Message | CustomMessage
+

Custom chat object given by LGHBot events, custom items avaiable if working about a group

+
+
CustomCallback : Object
+
+
LGHCallback : TelegramBot.CallbackQuery | CustomCallback
+

Custom callback object given by LGHBot events, custom items may be avaiable

+
+
chatsDatabase : Object
+

Object containing chat-related database functions.

+
+
usersDatabase : Object
+

Object containing user-related database functions.

+
+
LGHDatabase : Object
+

Type returned by the getDatabase function.

+
+
LibreGHelp : Object
+
+
+ + + +## LGHInterface +**Kind**: global class + +* [LGHInterface](#LGHInterface) + * [new LGHInterface(LibreGHelp)](#new_LGHInterface_new) + * [.GHbot](#LGHInterface+GHbot) : [LGHInterface](#LGHInterface) + * [.TGbot](#LGHInterface+TGbot) : [TelegramBot](https://github.com/yagop/node-telegram-bot-api/blob/master/doc/api.md) + * [.db](#LGHInterface+db) : [LGHDatabase](#LGHDatabase) + * [.config](#LGHInterface+config) : Object + * [.onMessage(handler)](#LGHInterface+onMessage) + * [.onCallback(handler)](#LGHInterface+onCallback) + * [.sendMessage(userId, chatId, text, options)](#LGHInterface+sendMessage) ⇒ Boolean \| Promise.<TelegramBot.Message> + * [.sendPhoto(userId, chatId, photo, options, fileOptions)](#LGHInterface+sendPhoto) ⇒ Boolean \| Promise.<TelegramBot.Message> + * [.editMessageMedia(userId, media, options)](#LGHInterface+editMessageMedia) ⇒ Boolean \| Promise.<TelegramBot.Message> + * [.editMessageText(userId, text, options)](#LGHInterface+editMessageText) ⇒ Promise.<Boolean> + * [.answerCallbackQuery(userId, callbackId, options)](#LGHInterface+answerCallbackQuery) ⇒ Promise.<Boolean> + * [.banChatMember(userId, chatId, targetId, options)](#LGHInterface+banChatMember) ⇒ Promise.<Boolean> + * [.unbanChatMember(userId, chatId, targetId, options)](#LGHInterface+unbanChatMember) ⇒ Promise.<Boolean> + * [.restrictChatMember(userId, chatId, targetId, options)](#LGHInterface+restrictChatMember) ⇒ Promise.<Boolean> + + + +### new LGHInterface(LibreGHelp) + +| Param | Type | Description | +| --- | --- | --- | +| LibreGHelp | [LibreGHelp](#LibreGHelp) | Libre Group Help telegram bot handler | + + + +### lghInterface.GHbot : [LGHInterface](#LGHInterface) +**Kind**: instance property of [LGHInterface](#LGHInterface) + + +### lghInterface.TGbot : [TelegramBot](https://github.com/yagop/node-telegram-bot-api/blob/master/doc/api.md) +**Kind**: instance property of [LGHInterface](#LGHInterface) + + +### lghInterface.db : [LGHDatabase](#LGHDatabase) +**Kind**: instance property of [LGHInterface](#LGHInterface) + + +### lghInterface.config : Object +**Kind**: instance property of [LGHInterface](#LGHInterface) + + +### lghInterface.onMessage(handler) +LGHbot message event handler + +**Kind**: instance method of [LGHInterface](#LGHInterface) + +| Param | Type | Description | +| --- | --- | --- | +| handler | function | handler function | + + + +### lghInterface.onCallback(handler) +LGHbot callback event handler + +**Kind**: instance method of [LGHInterface](#LGHInterface) + +| Param | Type | Description | +| --- | --- | --- | +| handler | function | handler function | + + + +### lghInterface.sendMessage(userId, chatId, text, options) ⇒ Boolean \| Promise.<TelegramBot.Message> +LGHbot safely send message under user request limit + +**Kind**: instance method of [LGHInterface](#LGHInterface) +**Returns**: Boolean \| Promise.<TelegramBot.Message> - - returns true on success, false if request has been dropped out + +| Param | Type | Description | +| --- | --- | --- | +| userId | number \| string | id of user that's the cause of your request | +| chatId | number \| string | chat where message should be sent | +| text | String | text of message | +| options | TelegramBot.SendMessageOptions | additional telegram options | + + + +### lghInterface.sendPhoto(userId, chatId, photo, options, fileOptions) ⇒ Boolean \| Promise.<TelegramBot.Message> +LGHbot safely send message under user request limit + +**Kind**: instance method of [LGHInterface](#LGHInterface) +**Returns**: Boolean \| Promise.<TelegramBot.Message> - - returns true on success, false if request has been dropped out + +| Param | Type | Description | +| --- | --- | --- | +| userId | | | +| chatId | number \| string | chat where message should be sent | +| photo | TelegramBot.InputMediaPhoto | photo | +| options | TelegramBot.SendPhotoOptions | additional telegram options | +| fileOptions | TelegramBot.FileOptions | file metadata | + + + +### lghInterface.editMessageMedia(userId, media, options) ⇒ Boolean \| Promise.<TelegramBot.Message> +**Kind**: instance method of [LGHInterface](#LGHInterface) +**Returns**: Boolean \| Promise.<TelegramBot.Message> - - returns true on success, false if request has been dropped out + +| Param | Type | Description | +| --- | --- | --- | +| userId | number \| string | id of user that's the cause of your request | +| media | TelegramBot.InputMedia | input media | +| options | TelegramBot.EditMessageMediaOptions | | + + + +### lghInterface.editMessageText(userId, text, options) ⇒ Promise.<Boolean> +LGHbot safely edit message under user request limit + +**Kind**: instance method of [LGHInterface](#LGHInterface) +**Returns**: Promise.<Boolean> - - returns true on success, false if request has been dropped out + +| Param | Type | Description | +| --- | --- | --- | +| userId | number \| string | id of user that's the cause of your request | +| text | String | text of message | +| options | TelegramBot.EditMessageTextOptions | additional telegram options | + + + +### lghInterface.answerCallbackQuery(userId, callbackId, options) ⇒ Promise.<Boolean> +LGHbot safely answerCallbackQuert under user request limit + +**Kind**: instance method of [LGHInterface](#LGHInterface) +**Returns**: Promise.<Boolean> - - returns true on success, false if request has been dropped out + +| Param | Type | Description | +| --- | --- | --- | +| userId | number \| string | id of user that's the cause of your request | +| callbackId | number \| string | id of user that's the cause of your request | +| options | TelegramBot.AnswerCallbackQueryOptions | additional telegram options | + + + +### lghInterface.banChatMember(userId, chatId, targetId, options) ⇒ Promise.<Boolean> +LGHbot safely answerCallbackQuert under user request limit + +**Kind**: instance method of [LGHInterface](#LGHInterface) +**Returns**: Promise.<Boolean> - - returns true on success, false if request has been dropped out + +| Param | Type | Description | +| --- | --- | --- | +| userId | number \| string | id of user that's the cause of your request | +| chatId | number \| string | - chat where message should be sent | +| targetId | number \| string | id of user that should be banned | +| options | TelegramBot.BanOptions | additional telegram options | + + + +### lghInterface.unbanChatMember(userId, chatId, targetId, options) ⇒ Promise.<Boolean> +LGHbot safely answerCallbackQuert under user request limit + +**Kind**: instance method of [LGHInterface](#LGHInterface) +**Returns**: Promise.<Boolean> - - returns true on success, false if request has been dropped out + +| Param | Type | Description | +| --- | --- | --- | +| userId | number \| string | id of user that's the cause of your request | +| chatId | number \| string | - chat where message should be sent | +| targetId | number \| string | id of user that should be unbanned | +| options | TelegramBot.UnbanOptions | additional telegram options | + + + +### lghInterface.restrictChatMember(userId, chatId, targetId, options) ⇒ Promise.<Boolean> +LGHbot safely answerCallbackQuert under user request limit + +**Kind**: instance method of [LGHInterface](#LGHInterface) +**Returns**: Promise.<Boolean> - - returns true on success, false if request has been dropped out + +| Param | Type | Description | +| --- | --- | --- | +| userId | number \| string | id of user that's the cause of your request | +| chatId | number \| string | - chat where message should be sent | +| targetId | number \| string | id of user to restrict | +| options | TelegramBot.RestrictChatMemberOptions | additional telegram options | + + + +## PermissionStatus : enum +Permission status +- 1: allowed +- 0: neutral +- -1: denied + +**Kind**: global enum +**Properties** + +| Name | Type | Default | +| --- | --- | --- | +| ALLOWED | number | 1 | +| NEUTRAL | number | 0 | +| DENIED | number | -1 | + + + +## testObject() ⇒ [LGHChat](#LGHChat) +**Kind**: global function +**Returns**: [LGHChat](#LGHChat) - testing jsdoc advices + + +## AnonTGUser : Object +Basic anonymized user object + +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| id | String \| Number | userId | + + + +## Punishment : 0 \| 1 \| 2 \| 3 \| 4 +Punishment to apply +- 0: off +- 1: warn +- 2: kick +- 3: mute +- 4: ban + +**Kind**: global typedef + + +## LGHPunish : Object +antispam.js settings Object. + +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| punishment | [Punishment](#Punishment) | Punishment to apply [0:off/1:warn/2:kick/3:mute/4:ban]. | +| PTime | Number \| null | Available if punishment is set to warn/mute/ban, contains seconds of punishment. | +| delete | boolean \| null | True if deletion is enabled as side effect. | + + + +## LGHChatBasedPunish : Object +Object to reresent different punish settings for more chat types + +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| channels | [LGHPunish](#LGHPunish) | Punish to apply for channels. | +| groups | [LGHPunish](#LGHPunish) | Punish to apply for groups. | +| users | [LGHPunish](#LGHPunish) | Punish to apply for users. | +| bots | [LGHPunish](#LGHPunish) | Punish to apply for bots. | + + + +## LGHAlphabetBasedPunish : Object +Object to reresent different punish settings for messages containing various Alphabets + +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| arabic | [LGHPunish](#LGHPunish) | Punish to apply for messages containing arabic characters. | +| cyrillic | [LGHPunish](#LGHPunish) | Punish to apply for messages containing cyrillic (russian) characters. | +| chinese | [LGHPunish](#LGHPunish) | Punish to apply for messages containing chinese characters. | +| latin | [LGHPunish](#LGHPunish) | Punish to apply for messages containing latin characters. | + + + +## TargetUser : Object +Object that refers to a target user + +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| id | string \| number | Telegram user Id | +| name | string | Full LGH name identifier: "fullName [id]" | +| perms | [LGHPerms](#LGHPerms) | LGHPerms with perms of target | +| user | TelegramBot.User \| null | If avaiable, target basic user object | + + + +## LGHPerms : Object +LGHPerms Object. + +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| commands | Array.<string> | Array of commands, if starts with "COMMAND_" means its to be translated, otherwise is the literal command. | +| immune | [PermissionStatus](#PermissionStatus) | Active if this user can't receive any punishment (kick/warn/mute/ban) [1/0/-1]. | +| flood | [PermissionStatus](#PermissionStatus) | Permission to flood messages [1/0/-1]. | +| link | [PermissionStatus](#PermissionStatus) | Permission to send links [1/0/-1]. | +| tgLink | [PermissionStatus](#PermissionStatus) | Permission to send telegram links/usernames [1/0/-1]. | +| forward | [PermissionStatus](#PermissionStatus) | Permission to forward messages from anywhere [1/0/-1]. | +| quote | [PermissionStatus](#PermissionStatus) | Permission to quote from anywhere [1/0/-1]. | +| porn | [PermissionStatus](#PermissionStatus) | Bypass porn/gore checks [1/0/-1]. | +| night | [PermissionStatus](#PermissionStatus) | Bypass any night mode limitation [1/0/-1]. | +| media | [PermissionStatus](#PermissionStatus) | Bypass any media limitation [1/0/-1]. | +| alphabets | [PermissionStatus](#PermissionStatus) | Bypass any alphabets characters limitations [1/0/-1]. | +| words | [PermissionStatus](#PermissionStatus) | Bypass banned words limitations [1/0/-1]. | +| length | [PermissionStatus](#PermissionStatus) | Bypass message length limitations [1/0/-1]. | +| roles | [PermissionStatus](#PermissionStatus) | Permission to change roles of lower level users [1/0/-1]. | +| settings | [PermissionStatus](#PermissionStatus) | Permission to change bot group settings [1/0/-1]. | + + + +## simpleMedia : Object +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| type | String \| null | Type of media (audio, photo, video, video_note, animation, sticker, document) or false | +| fileId | String | media fileId or false | +| options | Object | additional options for TelegramBot | + + + +## customMessage : Object +object of MessageMaker + +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| text | String | Text of messsage | +| entities | Array.<TelegramBot.MessageEntity> | Telegram entities of text | +| roles | Array.<String> | array user roles, string for pre-made roles, number for custom roles (user-made) | +| format | Boolean | true if message should be formatted (enabled by default), mean that entities should be passed on sendMessage function | +| media | [simpleMedia](#simpleMedia) | user administrator title | +| buttons | String | can be transformed in inline_keyboard with parseTextToInlineKeyboard() | +| buttonsParsed | Array.<TelegramBot.KeyboardButton> | already parsed buttons ready to use for inline_keyboard | + + + +## LGHAdminAdds : object +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| user | [AnonTGUser](#AnonTGUser) | Basic anonymized user object | +| status | TelegramBot.ChatMemberStatus | | + + + +## LGHAdmin : TelegramBot.ChatAdministratorRights \| [LGHAdminAdds](#LGHAdminAdds) +**Kind**: global typedef + + +## LGHAdminList : [Array.<LGHAdmin>](#LGHAdmin) +**Kind**: global typedef + + +## userStatus : Object +object with data about an user in a group + +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| firtJoin | Number | Unix number of first user join time in seconds, false if unknown (managed by welcome.js) | +| perms | [LGHPerms](#LGHPerms) | LGHPerms object for all user-specific permissions | +| adminPerms | [LGHPerms](#LGHPerms) | LGHPerms object for user permissions if admin | +| roles | Array.<String> | array user roles, string for pre-made roles, number for custom roles (user-made) | +| title | String \| undefined | user administrator title | +| waitingReply | String \| null | string with callback data hirarchy if bot is expecting a message from user on group | + + + +## LGHRole : Object +if pre-made role (string key) only users object should be used + +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| name | String \| null | role name | +| emoji | String \| null | emoji for the role | +| level | Number \| null | role level, higher level users can use commands that affect lower level users | +| perms | [LGHPerms](#LGHPerms) \| null | LGHPerms object applyed at lowest priority on any user in this role | +| users | Array.<String> | array of userId in this role | + + + +## LGHWarns : Object +warns.js plugin related data + +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| timed | Object.<string, Number> | ([userId]: [endTime, endTime, endTime]) contains necerray data to revoke scheduled warns when time is over | +| count | Object.<string, Number> | ([userId]: number) countains count of warns for each user | +| limit | Number | number of warns after wich should be applyed a punishment | +| punishment | 2 \| 3 \| 4 | punishment when limit is hit [2:kick/3:mute/4:ban] | +| PTime | Number \| null | avaiable if punishment is set to warn/mute/ban, contains seconds of punishment | + + + +## LGHWelcome : Object +welcome.js settings Object. + +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| state | boolean | True if welcome is enabled (default false). | +| once | boolean | True if should be sent only at first user join (default false). | +| clean | boolean | True if last welcome message on the group should be (default false). | +| joinList | Array.<(string\|number)> | cronology of users that joined the group over time. | +| lastWelcomeId | string \| number \| boolean | MessageId of last welcome message sent, useful if clean is enabled, false if never sent one before. | +| message | [customMessage](#customMessage) | CustomMessage object. | + + + +## LGHFloodAdds : Object +antiflood.js settings additional Object elements. + +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| messages | Number | Number of messages needed to trigger the Antiflood. | +| time | Number | Seconds within the specified message should be sent to trigger the Antiflood. | + + + +## LGHFlood : [LGHFloodAdds](#LGHFloodAdds) \| [LGHPunish](#LGHPunish) +antiflood.js settings Object. + +**Kind**: global typedef + + +## LGHSpamTgLinksAdds : Object +antispam.js settings Object additional items. + +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| usernames | Boolean | True if usernames should be considered as spam. | +| bots | Boolean | True if bots should be considered as spam. | +| exceptions | Array.<String> | Array of Telegram exceptions, may contain "Name:Id", `Name:|hidden` (for hidden users), or t.me link, or @username, "Name" | + + + +## LGHSpamTgLinks : [LGHSpamTgLinksAdds](#LGHSpamTgLinksAdds) \| [LGHPunish](#LGHPunish) +antispam.js settings about Telegram Links Object. + +**Kind**: global typedef + + +## LGHSpamLinksAdds : Object +antispam.js spam links Object additional items. + +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| exceptions | Array.<String> | Array of strings of allowed links or hostnames. | + + + +## LGHSpamLinks : [LGHSpamLinksAdds](#LGHSpamLinksAdds) \| [LGHPunish](#LGHPunish) +antispam.js settings about Links Object. + +**Kind**: global typedef + + +## LGHSpamForward : [LGHChatBasedPunish](#LGHChatBasedPunish) +antispam.js settings about foward. + +**Kind**: global typedef + + +## LGHSpamQuote : [LGHChatBasedPunish](#LGHChatBasedPunish) +antispam.js settings about quote. + +**Kind**: global typedef + + +## LGHSpam : Object +antispam.js settings Object. + +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| tgLinks | [LGHSpamTgLinks](#LGHSpamTgLinks) | rules and exceptions for telegram links considered as spam | +| links | [LGHSpamLinks](#LGHSpamLinks) | rules and exceptions for all links considered as spam | +| forward | [LGHSpamForward](#LGHSpamForward) | rules and exceptions for all forwarded messages considered as spam | +| quote | [LGHSpamQuote](#LGHSpamQuote) | rules and exceptions for all quoted messages considered as spam | + + + +## LGHGoodbye : Object +goodbye.js settings + +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| group | Boolean | True if goodbye should be sent on group | +| clear | Boolean | True if last goodbye message should be deleted before sending a new one | +| lastId | TelegramBot.MessageId | messageId of last goodbye message sent on group | +| gMsg | [CustomMessage](#CustomMessage) | Goodbye message to send on group | +| private | Boolean | True if goodbye should be sent on private chat | +| pMsg | [CustomMessage](#CustomMessage) | Goodbye message to send on private chat | + + + +## LGHCaptcha : Object +captcha.js settings + +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| state | Boolean | True if welcome is enabled (default false). | +| mode | string | Type of captcha, can be "image" (default "image"). | +| time | Number | Time limit to solve the captcha | +| once | boolean | True if should be sent only at first user join (from welcome.js) (default false). | +| fails | boolean | True if captcha should notify on group that someone failed the captcha (default false). | +| punishment | [Punishment](#Punishment) | Punishment to apply [1:warn/2:kick/3:mute/4:ban]. | +| PTime | Number | Available if punishment is set to warn/mute/ban, contains seconds of punishment. | + + + +## LGHMedia : Object +media.js settings, if LGHPunish is disabled the object will be deleted (undefinied) + +**Kind**: global typedef +**Properties** + +| Name | Type | +| --- | --- | +| photo | [LGHPunish](#LGHPunish) \| undefined | +| video | [LGHPunish](#LGHPunish) \| undefined | +| album | [LGHPunish](#LGHPunish) \| undefined | +| gif | [LGHPunish](#LGHPunish) \| undefined | +| voice | [LGHPunish](#LGHPunish) \| undefined | +| audio | [LGHPunish](#LGHPunish) \| undefined | +| sticker | [LGHPunish](#LGHPunish) \| undefined | +| sticker_video | [LGHPunish](#LGHPunish) \| undefined | +| dice | [LGHPunish](#LGHPunish) \| undefined | +| emoji_video | [LGHPunish](#LGHPunish) \| undefined | +| emoji_premium | [LGHPunish](#LGHPunish) \| undefined | +| video_note | [LGHPunish](#LGHPunish) \| undefined | +| file | [LGHPunish](#LGHPunish) \| undefined | +| game | [LGHPunish](#LGHPunish) \| undefined | +| contact | [LGHPunish](#LGHPunish) \| undefined | +| poll | [LGHPunish](#LGHPunish) \| undefined | +| location | [LGHPunish](#LGHPunish) \| undefined | +| capital | [LGHPunish](#LGHPunish) \| undefined | +| payment | [LGHPunish](#LGHPunish) \| undefined | +| via_bot | [LGHPunish](#LGHPunish) \| undefined | +| story | [LGHPunish](#LGHPunish) \| undefined | +| spoiler | [LGHPunish](#LGHPunish) \| undefined | +| spoiler_media | [LGHPunish](#LGHPunish) \| undefined | +| giveaway | [LGHPunish](#LGHPunish) \| undefined | +| mention | [LGHPunish](#LGHPunish) \| undefined | +| text_mention | [LGHPunish](#LGHPunish) \| undefined | +| hashtag | [LGHPunish](#LGHPunish) \| undefined | +| cashtag | [LGHPunish](#LGHPunish) \| undefined | +| command | [LGHPunish](#LGHPunish) \| undefined | +| url | [LGHPunish](#LGHPunish) \| undefined | +| email | [LGHPunish](#LGHPunish) \| undefined | +| number | [LGHPunish](#LGHPunish) \| undefined | +| bold | [LGHPunish](#LGHPunish) \| undefined | +| italic | [LGHPunish](#LGHPunish) \| undefined | +| underline | [LGHPunish](#LGHPunish) \| undefined | +| striketrough | [LGHPunish](#LGHPunish) \| undefined | +| quoteblock | [LGHPunish](#LGHPunish) \| undefined | +| closed_blockquote | [LGHPunish](#LGHPunish) \| undefined | +| code | [LGHPunish](#LGHPunish) \| undefined | +| pre_code | [LGHPunish](#LGHPunish) \| undefined | +| textlink | [LGHPunish](#LGHPunish) \| undefined | +| scheduled | [LGHPunish](#LGHPunish) \| undefined | +| effect | [LGHPunish](#LGHPunish) \| undefined | + + + +## CustomChat : Object +Additional chat elements for chat object by LibreGroupHelp + +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| admins | [LGHAdminList](#LGHAdminList) \| null | array with known admins objects (user data anonymized) | +| lang | String \| null | current chat lang | +| currency | String \| null | currency of chat, default to USD | +| link | string \| null | group access link | +| isGroup | Boolean | temporary item, result of `(chat.type == "supergroup" || chat.type == "group")` | +| users | Object.<string, userStatus> \| null | Object-IdName based data about every user in the group (ex. users[643547] access data of userId 643547) | +| roles | Object.<string, LGHRole> \| null | data about a specific role, full role Object if it's a custom role (key with a number) | +| basePerms | [LGHPerms](#LGHPerms) | base permissions applyed to every user | +| adminPerms | [LGHPerms](#LGHPerms) | base permissions applyed to admin | +| warns | [LGHWarns](#LGHWarns) \| null | warns.js plugin related data | +| rules | [customMessage](#customMessage) \| null | rules.js plugin related data | +| welcome | [LGHWelcome](#LGHWelcome) \| null | welcome.js plugin related data | +| flood | [LGHFlood](#LGHFlood) \| null | antiflood.js plugin related data | +| spam | [LGHSpam](#LGHSpam) \| null | antispam.js plugin related data | +| captcha | [LGHCaptcha](#LGHCaptcha) \| null | captcha.js plugin related data | +| goodbye | [LGHGoodbye](#LGHGoodbye) \| null | goodbye.js plugin related data | +| alphabets | [LGHAlphabetBasedPunish](#LGHAlphabetBasedPunish) \| null | alphabets.js plugin related data | +| media | [LGHMedia](#LGHMedia) \| null | media.js plugin related data | + + + +## LGHChat : TelegramBot.Chat \| [CustomChat](#CustomChat) +Full LGH chat object given by LGHBot events, custom items avaiable if working about a group + +**Kind**: global typedef + + +## CustomUser : Object +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| perms | [LGHPerms](#LGHPerms) \| null | temporary object with summary of user permissions | +| lang | String | current user lang | +| waitingReply | String | set to true if the bot is expecting a message from the user | + + + +## LGHUser : TelegramBot.User \| [CustomUser](#CustomUser) +Custom chat object given by LGHBot events, custom items avaiable if working about a group + +**Kind**: global typedef + + +## ParsedCommand : Object +ParsedCommand Object. + +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| text | string | The original text input. | +| prefix | string | The prefix used in the command (e.g., "/", "!", "."). | +| botCommand | string | The command with bot name (e.g., "start@usernamebot"). | +| name | string | The name of the command. | +| bot | string | The bot name (if available). | +| args | string \| boolean | The arguments of the command (optional). | +| splitArgs | Array.<string> \| boolean | The split arguments of the command (optional). | + + + +## CustomCommand : Object +Additional items to command for LGH + +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| target | [TargetUser](#TargetUser) \| null | Optional temporary object with data about a target LGH user in the command, false if no target found | + + + +## CustomMessage : Object +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| chat | [LGHChat](#LGHChat) | Always original chat object where the message is coming from | +| command | [ParsedCommand](#ParsedCommand) \| [CustomCommand](#CustomCommand) | result of message text parsed with parseCommand() | +| target | [TargetUser](#TargetUser) \| null | Optional temporary object with data about a command target | +| waitingReply | string \| null | Optional temporary object with waitingReply data for the selected chat | +| waitingReplyTarget | [TargetUser](#TargetUser) \| null | Optional temporary object with data about a target LGH user, false if no target found | + + + +## LGHMessage : TelegramBot.Message \| [CustomMessage](#CustomMessage) +Custom chat object given by LGHBot events, custom items avaiable if working about a group + +**Kind**: global typedef + + +## CustomCallback : Object +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| chat | [LGHChat](#LGHChat) | Always original chat object where the callback is coming from | +| target | [TargetUser](#TargetUser) | Optional temporary object with data about a target LGH user in the command, false if no target found | + + + +## LGHCallback : TelegramBot.CallbackQuery \| [CustomCallback](#CustomCallback) +Custom callback object given by LGHBot events, custom items may be avaiable + +**Kind**: global typedef + + +## chatsDatabase : Object +Object containing chat-related database functions. + +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| add | function | Function to add a new chat to the database. ------------------------------------ `function(TelegramBot.Chat): boolean` | +| delete | function | Function to delete a chat from the database. ------------------------------------ `function(TelegramBot.ChatId): boolean` | +| exhist | function | Function to check if a chat exhists in the database. ------------------------------------ `function(TelegramBot.ChatId): boolean` | +| get | function | Function to retrieve a chat from the database. ------------------------------------ `function(LGHChat): boolean` | +| update | function | Function to update a chat in the database. ------------------------------------ `function(LGHChat): boolean` | +| save | function | Function to save a chat to the database. ------------------------------------ `function(TelegramBot.ChatId): boolean` | + + + +## usersDatabase : Object +Object containing user-related database functions. + +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| add | function | Function to add a new user to the database. ------------------------------------ `function(TelegramBot.User): boolean` | +| delete | function | Function to delete a user from the database. ------------------------------------ `function(TelegramBot.ChatId): boolean` | +| exhist | function | Function to check if a user exhists in the database. ------------------------------------ `function(TelegramBot.ChatId): boolean` | +| get | function | Function to retrieve a user from the database. ------------------------------------ `function(TelegramBot.ChatId): LGHUser` | +| update | function | Function to update a user in the database. ------------------------------------ `function(LGHUser): boolean` | + + + +## LGHDatabase : Object +Type returned by the getDatabase function. + +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| innerDir | string | Location where the database folder should be placed (and/or generated). | +| dir | string | Full path to the database folder. | +| chatsDir | string | Full path to the chats folder within the database. | +| usersDir | string | Full path to the users folder within the database. | +| chats | [chatsDatabase](#chatsDatabase) | Object containing chat-related database functions. | +| users | [usersDatabase](#usersDatabase) | Object containing user-related database functions. | +| unload | function | Function to unload chats from memory. | + + + +## LibreGHelp : Object +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| GHbot | [LGHInterface](#LGHInterface) | Public interface for LGH Functions | +| TGbot | [TelegramBot](https://github.com/yagop/node-telegram-bot-api/blob/master/doc/api.md) | Raw telegram bot api | +| db | [LGHDatabase](#LGHDatabase) | Database interface | + diff --git a/docs/documentation/TODO-List.md b/docs/documentation/TODO-List.md new file mode 100644 index 0000000..0403fec --- /dev/null +++ b/docs/documentation/TODO-List.md @@ -0,0 +1,55 @@ +If you want an idea of what currently miss on the bot and you may want to implement it, that's the right page + +-short term: + + allow to edit single user perms + commands help panel + +-medium term: + + allow on /perms to change user perms and roles, +add it in a button for /info or when a role is set (/free /mod etc..), +ask double confirm to give an user the "settings" and "roles" permission + support for anonymous admins + allow to customize /staff allowing to set roles to hide + create a privacy setting where users can ask to esclude themself from tagResolver and replace his's first name in database with "Anonymous" + allow to disable tagResolver log on group settings + allow to mute only media, or specific media type or extras + create a privacy option to allow a user deleting his data from the bot + custom roles + optimize database.get, .update and .save to store in temporal array most used users + implement time zone setting +implement it in /info + +-long term: + + add log channel + chatIds anonymization on database + compress chats data stored on database + support all group help functions and more (+anti-sheduled messages[msg.is_from_offline], ) + allow bot clone bot when user give a token + add optionally an userbot (when active implement in tagResolver.js) + +-other things: + + user should have an option to delete also his warn or roles data from the entire database but accepting that he is going to be banned by any group where he got at least a warn and accepting that he is going to lose any acquired role on every group + implement direct private settings with /*settings + add a /commands command to help user to know bot commands, admin commands, and custom-group commands if avaiable + a check system to drop wrong formatted cb.data and waitingReply + allow to see perms calculation trough user perms, then roles by priority, then base group perms, going from left to right (or opposite) + add something to allow a group admin to identify all users with additional bot perms + ?add an automatic leveling system for admins? (maybe?) + add photo preview-mode in MessageMaker.js + allow to warn only usersIds who exhist on telegram, it can be checked if applyng a restriction returns true + add config to allow/disallow adding bot from non-admin users + ?identify reply_parameters and add everytime allow_sending_without_reply? (GHBot.js) + /geturl, by replying to a message (via reply) and writing this command, you receive the link that refers directly to that message. + /inactives [days] sends in private chat the list of users who have not sent a message in the last [days], with the possibility of punish them. + /pin [message] - sends the message through the Bot and pins it. + /editpin [message] - edits the current pinned message (if sent from the Bot). + /delpin - removes the pinned message. + /repin - removes and pins again the current pinned message, with notification! + /pinned - refers to the current pinned message. + /list - sends in private chat the list of users of the group with the number of messages sent by them. + /list roles - sends in private chat the list of all the special roles assigned to users + /graphic - sends a graph showing the trend of the group members. + /trend - sends the group's growth statistics. + /logdel - deletes the selected message and sends it to the Log Channel + /send - permits to send a post through the Bot with parse mode support \ No newline at end of file diff --git a/docs/documentation/callbacks.md b/docs/documentation/callbacks.md new file mode 100644 index 0000000..547b2e5 --- /dev/null +++ b/docs/documentation/callbacks.md @@ -0,0 +1,123 @@ +## LGH Hirarchy + +We need to expect button clicks and messages from users to be able to perform most of actions for our bot + + +That's why we need an unified hirarchy of how callbacks data are organized, on LibreGroupHelp they are avaiable for buttons on `cb.data` and `msg.waitingReply` for messages, we will talk about how to expect user messages soon, but first you should follow the right hirachy so main.js can set right variables for [LGH Events](events.md) + +
+ +That's the hirarchy: + +`CallbackName_opt1_opt2!data#editorName_opt1_opt2|editorData:groupId?targetUserId` + +
+ +It works too with less items like this: `CallbackName:groupId`, `CallbackName#editor?targetUserId`, `CallbackName:groupId?targetUserId`. + +
+ +**CallbackName** +Name of callback that you can use, be sure that not conflicts with other names, often plugins check if it's their match with `string.startsWith()`, `opt1` and `opt2` separated by `_` is avaiable to futher go deep with your callback listener + +--- + +**data** +Some additional data that you can attach to CallbackName (requires `CallbackName`) + +--- + +**editorName** +Also that is often identified with string.startsWith(), it's usually used by re-usable menus like MessageMaker.js, setNum.js, setTime.js + +[What are editors?](editors.md) + +--- + +**editorData** +Additional data that editor may attach (requires `editorName`) + +--- + +**groupId** +This value when given allow main.js to set by any chat context a specific full chat object on it's events inside [GHBot](GHBot.md/#LGHInterface) (`msg.chat` or `cb.message.chat` are not affected) and `user.perms` related to user permissions on the given groupId + +[Read how groupId helps LGH Events](events.md/#expect-messages) + +--- + +**targetUserId** +This value when given allow main.js to set a specific target user in various cases: `cb.target`, `msg.waitingReplyTarget` (note: it's volontarily separated from `msg.target` that's command target dedicated) + +[Read how targetUserId helps LGH Events](events.md/#target-user) + +--- + + +## Expect user messages + +In this example i will show you how to expect futher message from user and, listen it back when he replicate, and then disable futher message expectations + +For messages callbacks comes at help 2 functions: + + waitReplyForChat(database, callback, user, chat, onGroup) + unsetWaitReply(database, user, chat, onGroup) + +
+ +Keep in mind that Callback Hirarchy upon explained has to be followed + +```javascript +const LGHelpTemplate = require("../GHbot.js") +const {waitReplyForChat, unsetWaitReply} = require( "../api/utils/utils.js" ); + +function main(args) +{ + + const GHbot = new LGHelpTemplate(args); + const {TGbot, db, config} = GHbot; + + GHbot.onMessage( (msg, chat, user) => { + + if(msg.text != "/guess") return; + + //if users type /guess expect a message with "EXPECT_PASSWORD" callback + + /** + * waitReplyForChat, if chat.isGroup == false, will set + * automatically the callback as EXAMPLE:groupId + */ + waitReplyForChat(db, "EXPECT_PASSWORD", user, chat, chat.isGroup) + + GHbot.sendMessage(user.id, chat.id, "Guess the password") + + }) + + GHbot.onMessage( (msg, chat, user) => { + + var isMyCallback = msg.waitingReply && msg.waitingReply.startsWith("EXPECT_PASSWORD") + if(!isMyCallback) return; + + if(msg.text == "password1234"){ + GHbot.sendMessage(user.id, chat.id, "Congratulation, password guessed!") + unsetWaitReply(db, user, chat, chat.isGroup) //do not expect futher messages + } + else{ + GHbot.sendMessage(user.id, chat.id, "Password incorrect, try again ): ") + } + + }) + +} + +module.exports = main; +``` + +When you are expecting a message other plugins will see (with `msg.waitingReply` != false) your decision and they may stop working until you finished, so be sure to use unsetWaitReply eventually + + +## Expect user button clicks + +Currently LGH has no special procedure to expect button clicks, just follow the hirarchy and do how you would do with [TGbot](https://github.com/yagop/node-telegram-bot-api/blob/master/doc/api.md) + +You find an example here: [LGH Events: Expect buttons clicks](events.md/#expect-buttons-clicks) diff --git a/docs/documentation/commands.md b/docs/documentation/commands.md new file mode 100644 index 0000000..71d3958 --- /dev/null +++ b/docs/documentation/commands.md @@ -0,0 +1,184 @@ +# Create a command + +LibreGroupHelp offers multi-language command support, when the user sends a command LGH will try to resolve the command trying first to translate the raw one to the command code (usually starting with `COMMAND_`), then, if registered, their function will be ran + + +## Create command lang-code + +Before registering your first command you need to know how to add it to the bot dictionary + +Open `langs/en_en.json` and scroll down below until you find the values keys starting with `"COMMAND_"` + +```json +"/rules": "COMMAND_RULES", +"/regulation" : "COMMAND_RULES", +"COMMAND_RULES" : "rules", +"CMDDESC_RULES" : "/{name} or /regulation\nSend group regulament message, it can be changed in settings", +"/permissions": "COMMAND_PERMS", +"/perms": "COMMAND_PERMS", +"COMMAND_PERMS" : "perms", +``` + +As you see, `"COMMAND_RULES" : rules` define the main command as the `/rules` one +But it owns also some alias, still linked to `COMMAND_RULES` + +```json +"/rules": "COMMAND_RULES", +"/regulation" : "COMMAND_RULES", +``` + +Both `/rules` and `/regulation` will fire up the same function + +We see also a `"CMDDESC_RULES"` parameter with a `{name}` substitution key, set this value can help back in some cases where bot has to show a short description of what the command does, it's not mandatory to add this but is reccomended + +
+ +Now add our own command + +```json +"/example" : "COMMAND_EXAMPLE", +"/showcase" : "COMMAND_EXAMPLE", +"/anotheralias" : "COMMAND_EXAMPLE", +"COMMAND_EXAMPLE" : "example", +"CMDDESC_EXAMPLE" : "/{name} or /showcase or /anotheralias\nThese are just commands to show an example on LibreGroupHelp Wiki" +"/rules": "COMMAND_RULES", +"/regulation" : "COMMAND_RULES", +"COMMAND_RULES" : "rules", +"CMDDESC_RULES" : "/{name} or /regulation\nSend group regulament message, it can be changed in settings", +"/permissions": "COMMAND_PERMS", +"/perms": "COMMAND_PERMS", +"COMMAND_PERMS" : "perms", +``` + +We added as main command of `COMMAND_EXAMPLE` the command `/example`, anyway also `/showcase` and `/anotheralias` are avaiable as aliases + +*Note: `"/example" : "COMMAND_EXAMPLE"` and `"COMMAND_EXAMPLE" : "example"` are always both needed, even if example is already described as the main command, it has to be anyway in the aliases list* + +--- + +## Register command + +The command registering tool can be required with +`const GHCommand = require("../api/tg/LGHCommand.js")` + +To reply a command the right procedure is using the sendCommandReply utility (from `api/utils/utils.js` ) + +Giving back to `sendCommandReply` the `GHCommand.registerCommand` parameters will allow it to decide what is the correct destination chat to reply, running then a callback that gives you a `chadId` where to reply + +That's because the user may have the permission to use this command only with a private bot reply, but there are also many other caveuts, this system will handle everything for you, so you can focus on the acutal command creation + +Here an example: + +```javascript +const { sendCommandReply } = require("../api/utils/utils.js"); +const GHCommand = require("../api/tg/LGHCommand.js"); +const LGHelpTemplate = require("../GHbot.js"); + +function main(args) +{ + + const GHbot = new LGHelpTemplate(args); + const {TGbot, db, config} = GHbot; + + GHCommand.registerCommands(["COMMAND_EXAMPLE"], (msg, chat, user, private, lang, key, keyLang) => { + + //we want this command to work only if from groups + if(!msg.chat.isGroup) return; + + sendCommandReply(private, lang, GHbot, user.id, chat.id, (sendId)=>{ + var text = "Thanks for the interest into LGH, we appreciate this"; + GHbot.sendMessage(user.id, sendId, text); + }) + + }) + +} + +module.exports = main; +``` + +If are you sure that your command reply has always to be on the group you can still set `false` instead of `private` on `sendCommandReply` + +In the same way if your command reply should be always on private chat, you set `true` instead of `private` + +*Note: `msg`, `chat` and `user` are exactly the same parameters you get within [LGH Events](events.md/#expect-messages), they come acutally from there* + + +## Some insights + +Any [msg](GHBot.md/#lghmessage-telegrambotmessage-custommessage) object contains [msg.command](GHBot.md/#parsedcommand-object), can be useful to handle more parameters on your command + +--- + +Why first parameter of `GHCommand.registerCommands` is an array? +Yes it's exactly what you think, you can run the same function for more commands, but why? + +I will show you this directly using `promote.js` plugin as example + + +```javascript +var commandsList = ["COMMAND_FREE", "COMMAND_UNFREE", "COMMAND_HELPER", "COMMAND_UNHELPER", "COMMAND_CLEANER", "COMMAND_UNCLEANER", + "COMMAND_MUTER", "COMMAND_UNMUTER", "COMMAND_MODERATOR", "COMMAND_UNMODERATOR", "COMMAND_COFOUNDER", "COMMAND_UNCOFOUNDER", + "COMMAND_ADMINISTRATOR", "COMMAND_UNADMINISTRATOR", "COMMAND_TITLE", "COMMAND_UNTITLE"]; + +GHCommand.registerCommands(commandsList, async (msg, chat, user, private, lang, key, keyLang) => { + if(!msg.chat.isGroup) return; + + /** + * note how we return in case of msg.waitingReply, that's because + * otherwise we would handle this command also while the user is + * dealing with some other piece of the bot + * */ + if(msg.waitingReply) return; + + var command = msg.command; + var lang = msg.chat.lang; + var target = msg.waitingReplyTarget || msg.target; + var text = false; + var options = {parse_mode : "HTML"}; + var toSetRole = false; + var toUnsetRole = false; + + if( key == "COMMAND_FREE") + toSetRole = "free"; + if( key == "COMMAND_UNFREE") + toUnsetRole = "free"; + + if( key == "COMMAND_HELPER") + toSetRole = "helper"; + if( key == "COMMAND_UNHELPER") + toUnsetRole = "helper"; + + if( key == "COMMAND_CLEANER") + toSetRole = "cleaner" + if( key == "COMMAND_UNCLEANER") + toUnsetRole = "cleaner"; + + if( key == "COMMAND_MUTER") + toSetRole = "muter"; + if( key == "COMMAND_UNMUTER") + toUnsetRole = "muter"; + + if( key == "COMMAND_MODERATOR") + toSetRole = "moderator"; + if( key == "COMMAND_UNMODERATOR") + toUnsetRole = "moderator"; + + if( key == "COMMAND_COFOUNDER") + toSetRole = "cofounder" + if( key == "COMMAND_UNCOFOUNDER") + toUnsetRole = "cofounder"; + + if( key == "COMMAND_ADMINISTRATOR"){...} + if( key == "COMMAND_UNADMINISTRATOR"){...} + if( key == "COMMAND_TITLE"){...} + if( key == "COMMAND_UNTITLE"){...} + + //check if user can change a role and if he can apply it to target + if(toSetRole || toUnsetRole){...} + if(toSetRole){...} + if(toUnsetRole){...} +}) +``` + +As you see, in this case we need to listen for multiple commands at the same time as they need to run pretty the same code, we need only `key` to change `toSetRole` and `toUnsetRole` variable, then the code is same for everyone diff --git a/docs/documentation/database.md b/docs/documentation/database.md new file mode 100644 index 0000000..1b8f75a --- /dev/null +++ b/docs/documentation/database.md @@ -0,0 +1,74 @@ +# Database + +As you may have seen by many examples, an object that we always get is [db](GHBot.md/#LGHDatabase) (database) + +```javascript +const LGHelpTemplate = require("../GHbot.js") + +function main(args) +{ + + const GHbot = new LGHelpTemplate(args); + const {TGbot, db, config} = GHbot; + ... +} + +module.exports = main; +``` + +[Database](GHBot.md/#LGHDatabase) is the core of LibreGroupHelp to store chat and users data, as to the privacy implications of that we aim to minimize the amount of sensitive data there and anyway we keep in mind that the user should be able to remove any trace of him there + +## Database usage + +Currently [database](GHBot.md/#LGHDatabase) let you control [chats](GHBot.md/#chatsDatabase) and [users](GHBot.md/#usersDatabase) using same interface of functions + +You are supposed to use `update` method everytime you want to apply changes to one of them + +```javascript +const LGHelpTemplate = require("../GHbot.js") + +function main(args) +{ + + const GHbot = new LGHelpTemplate(args); + const {TGbot, db, config} = GHbot; + + GHbot.onMessage( (msg, chat, user) => { + + if(!chat.isGroup) return; + + if( msg.text == "/antiflood kind" ) + { + chat.flood.messages = 8; + chat.flood.time = 10; + db.chats.update(chat); //apply changes to database + GHbot.sendMessage( user.id, chat.id, "Antiflood set to be kind" ); + } + else if( msg.text == "/antiflood hard" ) + { + chat.flood.messages = 3; + chat.flood.time = 5; + db.chats.update(chat); //apply changes to database + GHbot.sendMessage( user.id, chat.id, "Antiflood set to be hard" ); + } + + if( msg.text == "/anonymize" ) + { + user.first_name = "anonymous" + user.last_name = "anonymous" + db.users.update(users); //apply changes to database + GHbot.sendMessage( user.id, chat.id, "Anonymized successfully" ); + } + + } ) + +} + +module.exports = main; +``` +You find all relative methods documented clicking [db.chats](GHBot.md/#chatsDatabase) and [db.users](GHBot.md/#usersDatabase) + +--- + + +*Note: as written on [Known issues](known-issues.md) there are a problem with [chats](GHBot.md/#chatsDatabase) interface of database wich gives a reference copy of a LGHChat object, that's mean that it may be eventually stored on database even without `update` functions, fixing this would require some code refacory, you should still follow the rule of using `update` to confirm changes, if you need to apply only temporary changes of an LGHChat object please make a deep copy* \ No newline at end of file diff --git a/docs/documentation/editors.md b/docs/documentation/editors.md new file mode 100644 index 0000000..bc9e54d --- /dev/null +++ b/docs/documentation/editors.md @@ -0,0 +1,99 @@ +# What are editors? + +Editors are a way create re-usable interfaces of panels, with their expect messages and expect buttons callbacks handling to allow you to show something to an user or edit a variable, object, or something else + +As you already know by [LGH Hirarchy](callbacks.md/#lgh-hirarchy), editors has their own space there, the reason why we need to make them separate is simple: +You still need to know who is the caller of the editor it's so can correctly handle like a possible variable change + +Let's begin from the most useful of the editors, `MessageMaker`, that allow the user to modify a [customMessage](GHBot.md/#custommessage-object) object and then also to send it as a telegram message + +That's how `rules.js` uses that (some code not interested has been suppressed): + +```javascript +const LGHelpTemplate = require("../GHbot.js"); +const {sendCommandReply, waitReplyForChat, unsetWaitReply} = require( "../api/utils/utils.js" ); +const MSGMK = require( "../api/editors/MessageMaker.js" ) +... + +function main(args) +{ + + const GHbot = new LGHelpTemplate(args); + const {TGbot, db, config} = GHbot; + ... + + GHbot.onMessage( async (msg, chat, user) => { + + //check if it's our callback + if(!chat.isGroup) return; + if( !(msg.waitingReply && msg.waitingReply.startsWith("S_RULES")) ) return; + ... + + /** + * rules never expect for other messages + * so we can give it all directly to MessageMaker hands + */ + var customMessage = await MSGMK.messageEvent(GHbot, db, chat.rules, msg, chat, user, "S_RULES"); + + //then if customMessage has an update, we save that + if(customMessage) + { + chat.rules = customMessage; + db.chats.update(chat); + } + + } ) + + + GHbot.onCallback( (cb, chat, user) => { + + var msg = cb.message; + var lang = user.lang; + + //check if it's our callback + if(!chat.isGroup) return; + if( !cb.data.startsWith("S_RULES")) return; + ... + + //from rules panel we add a button to access MessageMaker + if( cb.data.startsWith("S_RULES_BUTTON:") ) + { + + GHbot.editMessageText( user.id, l[lang].RULES_SETTING, { + ... + reply_markup : {inline_keyboard :[ + [{ + text: l[lang].RULES_CHANGE_BUTTON, + //we give a button to access MessageMaker + callback_data: "S_RULES#MSGMK:"+chat.id + }], + ... + ]}}) + GHbot.answerCallbackQuery(user.id, cb.id); + } + + //we listen here back for requested MessageMaker accesses + if( cb.data.startsWith("S_RULES#MSGMK") ) + { + var returnButtons = [[{text: l[lang].BACK_BUTTON, callback_data: "S_RULES_BUTTON:"+chat.id}]]; + var title = l[lang].REGULATION; + var msgTitle = l[lang].RULES_TITLE; + //giving the buttons handling to MessageMaker hands + var customMessage = MSGMK.callbackEvent(GHbot, db, chat.rules, cb, chat, user, "S_RULES", returnButtons, title, msgTitle) + + //then if customMessage has an update, we save that + if(customMessage) + { + chat.rules = customMessage; + db.chats.update(chat); + } + } + ... + }) +} + +module.exports = main; + +``` + +The access point of MessageMaker is trough buttons callbacks, but it works then with the user also by expecting messages, so we need to forward also them diff --git a/docs/documentation/events.md b/docs/documentation/events.md new file mode 100644 index 0000000..1e09aa3 --- /dev/null +++ b/docs/documentation/events.md @@ -0,0 +1,307 @@ +# Events + +ONLY for events from GHBot you have additional elements on parameters bot-related + +Usually GHBot events has 3 parameters: +([callback](./GHBot.md/#lghcallback-telegrambotcallbackquery-customcallback) +or +[message](GHBot.md/#lghmessage-telegrambotmessage-custommessage)), +[chat](GHBot.md/#LGHChat), +[user](GHBot.md/#LGHUser) + +GHBot currently has 2 events fully supported + +```javascript +GHBot.onCallback( (cb, chat, user) => { console.log(cb) } ) +GHBot.onMessage( (msg, chat, user) => { console.log(msg) } ) +``` + +--- + +##Chat data + +So how [GHBot](GHBot.md/#LGHInterface) enchanches events for LibreGroupHelp more than using the raw [TGBot](https://github.com/yagop/node-telegram-bot-api/blob/master/doc/api.md)? + +First at all, it allow us to get already a full chat object from the database, thus giving you the full chat configuration + +```javascript +const { punishmentToFullText } = require("../api/utils/utils.js"); +const LGHelpTemplate = require("../GHbot.js") + +function main(args) +{ + + const GHbot = new LGHelpTemplate(args); + const {TGbot, db, config} = GHbot; + + GHbot.onMessage( (msg, chat, user) => { + + var runTest = msg.chat.isGroup && msg.text == "/test" + if( !runTest ) return; + + console.log("Logging chat flood settings") + console.log("Message limit: " + msg.chat.flood.messages) + console.log("Fire if sent within " + msg.chat.flood.time + " seconds") + var punish = punishmentToFullText(user.lang, msg.chat.flood.punishment, msg.chat.flood.PTime, msg.chat.flood.delete) + console.log("User will be punished with " + punish) + + } ) + +} + +module.exports = main; +``` + +Output if any user type `/test` on a group: + + Logging chat flood settings + Message limit: 3 + Fire if sent within 5 seconds + User will be punished with Warn for 1 day + delete + +*You may wonder why we use msg.chat instead of chat? You get that in detail on [Expect messages](events.md/#expect-messages) section, shotly it's because we want to work on the chat where the message is coming from, not the select chat* + +--- + +## User permissions + +We may also want to allow the user to change settings, but we need to know if he has the permission to do that, so we have [user.perms](GHBot.md/#LGHPerms) containing a permissions object about the user on that chat + +*Note: [user.perms](GHBot.md/#LGHPerms) is a temporary item* + +```javascript +const LGHelpTemplate = require("../GHbot.js") + +function main(args) +{ + + const GHbot = new LGHelpTemplate(args); + const {TGbot, db, config} = GHbot; + + GHbot.onMessage( (msg, chat, user) => { + + if(!chat.isGroup) return; + + //we never listen to commands like this on LGH, it's just as example + if( !msg.text.startsWith("/antiflood") ) return + + //Check for user permissions to change settings + if(user.perms.settings != 1) + { + GHbot.sendMessage(user.id, chat.id, "You haven't settings permission"); + return; + } + + if( msg.text == "/antiflood kind" ) + { + chat.flood.messages = 8; + chat.flood.time = 10; + db.chats.update(chat); //apply changes to database + GHbot.sendMessage( user.id, chat.id, "Antiflood set to be kind" ); + } + else if( msg.text == "/antiflood hard" ) + { + chat.flood.messages = 3; + chat.flood.time = 5; + db.chats.update(chat); //apply changes to database + GHbot.sendMessage( user.id, chat.id, "Antiflood set to be hard" ); + } + + } ) + +} + +module.exports = main; +``` + +--- + +## Expect messages + +[GHBot](GHBot.md/#LGHInterface) makes also you easy to expect messages or callbacks from users in private chat and both still relating to the group, keeping the group [chat](GHBot.md/#LGHChat) object + +Let's see: + +```javascript +const { unsetWaitReply, waitReplyForChat } = require("../api/utils/utils.js"); +const LGHelpTemplate = require("../GHbot.js") + +function main(args) +{ + + const GHbot = new LGHelpTemplate(args); + const {TGbot, db, config} = GHbot; + + GHbot.onMessage( async (msg, chat, user) => { + + if(!msg.chat.isGroup) return; + + if(msg.text == "/antiflood") + { + /** + * waitReplyForChat, if chat.isGroup == false, will set + * automatically the callback as EXAMPLE:groupId + */ + waitReplyForChat(db, "EXAMPLE", user, chat, chat.isGroup); + var text = `Ok, antiflood should be kind or hard?\n`+ + `You can reply both here or private chat\n`+ + `@${TGbot.me.username}`; + GHbot.sendMessage(user.id, chat.id, text); + } + + } ) + + GHbot.onMessage( (msg, chat, user) => { + + + /** + * Here, if msg.waitingReply has a groupId (ex. EXAMPLE:-109848493476) + * so it's following correctly the LGH Callbacks Hirarchy, + * the "chat" parameter would be bind to the group + * enriched by the database, we have a full LGH chat object + */ + + //So behaivor is different from "if(!msg.chat.isGroup) return" + if(!chat.isGroup) return; //think that as "!selectedChat.isGroup" + if( !msg.waitingReply.startsWith("EXAMPLE") ) return; + + //even on private chat, user.perms still exhist if a group is binded + if(user.perms.settings != 1) + { + GHbot.sendMessage(user.id, chat.id, "You haven't settings permission"); + return; + } + + if( msg.text == "kind" ) + { + chat.flood.messages = 8; + chat.flood.time = 10; + db.chats.update(chat); //apply changes to database + GHbot.sendMessage( user.id, chat.id, "Antiflood set to be kind" ); + unsetWaitReply(db, user, chat, chat.isGroup); + } + else if( msg.text == "hard" ) + { + chat.flood.messages = 3; + chat.flood.time = 5; + db.chats.update(chat); //apply changes to database + GHbot.sendMessage( user.id, chat.id, "Antiflood set to be hard" ); + unsetWaitReply(db, user, chat, chat.isGroup); + } + + //msg.chat keeps for sure the chat wich message is coming from + var text = `This message is from private chat? ${!msg.chat.isGroup}`; + GHbot.sendMessage( user.id, chat.id, text); + + } ) + +} + +module.exports = main; +``` + +--- + + + +## Expect buttons clicks + +Buttons callbacks works pretty in the same way: + +```javascript +const { punishmentToFullText } = require("../api/utils/utils.js"); +const LGHelpTemplate = require("../GHbot.js"); + +function main(args) +{ + + const GHbot = new LGHelpTemplate(args); + const {TGbot, db, config} = GHbot; + + GHbot.onMessage( async (msg, chat, user) => { + + if(!msg.chat.isGroup) return; + + //we never listen to commands like this on LGH, it's just as example + if(msg.text == "/private") + { + var text = "Proceed on private chat\n@"+TGbot.me.username; + var buttons = [[ + { + //As you see we follow the hirarchy + callback_data: "EXAMPLE_SHOW_CONFIG:"+chat.id, + text: "Show antiflood config" + } + ]]; + var options = {reply_markup:{inline_keyboard:buttons}}; + GHbot.sendMessage(user.id, user.id, text, options); + } + + } ) + + GHbot.onCallback( (cb, chat, user) => { + + /** + * Also here, if cb.data has a groupId (ex. EXAMPLE:-109848493476) + * following correctly the LGH Callbacks Hirarchy + * the "chat" parameter would be bind to the group + * enriched by the database we have a full LGH chat object + */ + + if(!chat.isGroup) return; + + //callback data is stored on cb.data + if( !cb.data.startsWith("EXAMPLE") ) return + + /** + * Note: we use cb.chat.id, because editMessageText + * needs the chatId where callback is coming from + */ + var editOpts = { + message_id: cb.message.message_id, + chat_id: cb.chat.id, + } + + if(user.perms.settings != 1) + { + GHbot.editMessageText(user.id, "You haven't settings permission", editOpts); + return; + } + + if( cb.data.startsWith("EXAMPLE_SHOW_CONFIG") ) + { + var punish = punishmentToFullText(user.lang, chat.flood.punishment, chat.flood.PTime, chat.flood.delete) + var text = `Chat flood settings + Message limit: ${chat.flood.messages} + Fire if sent within ${chat.flood.time} seconds + User will be punished with ${punish}` + GHbot.editMessageText(user.id, text, editOpts); + } + + //cb.chat keeps for sure the chat wich message is coming from + GHbot.sendMessage( user.id, chat.id, "This callback is from private chat? " + !cb.chat.isGroup ); + + } ) + +} + +module.exports = main; +``` + +## Target user + +As you may have seen from the [LGH Callbacks hirarchy](callbacks.md/#lgh-hirarchy), after `?` exhists a parameter for target users, this callback parameter allows you to bind an user intended to be affected in some way trough the callback, so he is going to be avaiable on [cb.target](GHBot/#targetuser-object) or [msg.waitingReplyTarget](GHBot/#targetuser-object) + +--- + +If you need instead data about a direct target of a message you have msg.target + +These are some cases where [msg.target](GHBot/#targetuser-object) appears: +User X, replying to User Y, Y is the target +User X, use a command mentioning Y (ex. `/ban @UserY`), Y is the target + +That comes useful while handling a command after a [Command creation](commands.md) + +## Conclusion + +Is better to think about the [chat](GHBot.md/#LGHChat) parameter as the selected chat, not the chat we are (that's on msg.chat), but the chat where we are asked to work on diff --git a/docs/documentation/index.md b/docs/documentation/index.md new file mode 100644 index 0000000..e1b6801 --- /dev/null +++ b/docs/documentation/index.md @@ -0,0 +1,18 @@ +# GHBot documentation + +## How it works + +Begin point is from `index.js` which loads [plugins](./plugins.md), database and the acutal bot is then started by main.js + +Other than starting the bot `main.js` emits on [GHBot](GHBot.md/#LGHInterface) some [events](events.md) with many LibreGroupHelp related integrated data ready to use, simplyfing the code + +[Database](database.md) is managed by `database.js`, usually on the `db` variable, main methods are found on db.chats and db.users to manage data about them + +[JSDocs Objects](GHBot.md) documentation are on `GHbot.js`, it may also implement small fixes always to make an easyer interface + +[TGbot](https://github.com/yagop/node-telegram-bot-api/blob/master/doc/api.md) variable will give you direct access to the [telegram-bot-api](https://github.com/yagop/node-telegram-bot-api), when possible you should use GHbot events and methods and if does not exhist the one needed create that +*Additionally on [TGbot.me](https://core.telegram.org/bots/api#getme) is avaiable `await TGbot.getMe()` result* + +Any LibreGroupHelp code should keep in mind that user should be able to delete his data in any moment, that's for respecting at best our privacy philosophy + +[Github good first issues](https://github.com/Sp3rick/GroupHelp/contribute) \ No newline at end of file diff --git a/docs/documentation/known-issues.md b/docs/documentation/known-issues.md new file mode 100644 index 0000000..379b7d9 --- /dev/null +++ b/docs/documentation/known-issues.md @@ -0,0 +1,11 @@ +# Known possible bugs: + +-sometimes db.chats.update in plugins may be not used at all because you can still edit the global object cause to reference, not using it may cause some issue. +if global reference get cleared too early code may try to access and inexistent variable + +-cleanHTML() may be not applyed in some text where it should, and nothing assure that it's 100% able to clean everything needed for telegram api + +-if you add a new permission on userPerms object, every userPerms object should be updated adding that, otherwise this may cause incorrect result in sumUserPerms + +-in some unkown cases you may get stuck in exceptions menu and SafeGram.js will block any user request due too high accumulated volume of something pending + +-permissions setup on first bot adding to groups is not the same as using /reload that's more complete \ No newline at end of file diff --git a/docs/documentation/languages.md b/docs/documentation/languages.md new file mode 100644 index 0000000..7d64f60 --- /dev/null +++ b/docs/documentation/languages.md @@ -0,0 +1,28 @@ +## Language info + +LibeGrouHelp has a language configuration for users (user.lang) and for groups (chat.lang) + +When our bot is added to a group the default group language will be inherited from the user who added LGH Bot + +*Note: currently LGH does not inherit the user language from it's device telegram settings, but it's planned as a future feature* + +`global.LGHLangs` is an object with every language translation loaded +Usually plugins get that using `l = global.LGHLangs` +To translate use this format: `l[lang].KEY` + +Don't bother for missing keys in case of missing translation, every missing key is already replaced with the english one version + + +## Extend bot dictionary + +The main language is english, so open `langs/en_en.json` and simply insert new parameters there + +```json +"FLAG" : "🇬🇧", +"LANG_SELECTOR" : "🇬🇧 English", +"LANG_NAME" : "International English", +"LANG_SHORTNAME" : "English", +"LANG_CHOOSE" : "🇬🇧 Choose your language", +"LANG_CHOOSE_GROUP" : "🇬🇧 Choose group language", +"EXAMPLE_MESSAGE" : "This a new item on dictionary for wiki example" +``` \ No newline at end of file diff --git a/docs/documentation/plugins.md b/docs/documentation/plugins.md new file mode 100644 index 0000000..2cf5b41 --- /dev/null +++ b/docs/documentation/plugins.md @@ -0,0 +1,34 @@ +# Plugins + +You can create any plugin you want creating a new file inside `plugins` folder + +Look at `example.js` to see how it should be organized: + +```javascript +const LGHelpTemplate = require("../GHbot.js") + +function main(args) +{ + + const GHbot = new LGHelpTemplate(args); + const {TGbot, db, config} = GHbot; + + //here your plugin code// + + l = global.LGHLangs; //importing langs object + + GHbot.onMessage( (msg, chat, user) => { + + if( chat.type == "private" && msg.text == "/test999" ) + GHbot.sendMessage( user.id, chat.id, "Hello, i send this because im a plugin\n"+l[user.lang].flag ); + + } ) + + +} + +module.exports = main; +``` + +Put and import in your plugin any needed utility on `api` folder, but if you know that some functions will be ever needed only on your plugin, you are free to declare it directly there + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..8b67ce9 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,93 @@ +# LibreGroupHelp + +Open-Source re-creation of telegram group manager Group Help in NodeJS based on [node-telegram-api](https://github.com/yagop/node-telegram-bot-api). + +An official instance of bot is running on [@LibreGroupHelpBot](https://t.me/LibreGroupHelpBot) + +## Installation: + +Be sure to have installed a recent version of [NodeJS](https://nodejs.org/) + +Verify NodeJS installation with `node -v` + +Set your bot token using configuration file, look at [config documentation](configuration.md). + +Open a terminal inside LibreGroupHelp folder and run this commands + +```bash +npm install +``` + +Now you should be ready to run LibreGroupHelp using: +```bash +node index.js +``` + + +## What is done + +✅ Completed and working + +🟡 Not fully implemented (work in progress) + +❌ Not implemented at all + +``` +✅ Roles and permissions hirarchy +❌ Custom roles +✅ Moderation commands +❌ Support moderation for channels users +❌ Support for anonymous admins +🟡 Bot support +❌ Bot help (how to use) +❌ Bot clones support +❌ UTC Time settings +✅ Langs and lang settings +✅ Rules +✅ Welcome +✅ Anti-flood +✅ Anti-spam +✅ Goodbye +✅ Alphabets +✅ Captcha (1 mode) +❌ Checks settings +❌ @Admin +❌ Blocks settings +✅ Media blocks +❌ Anti-NSFW +✅ Warns settings +❌ Nigth mode +❌ Tag settings +✅ Link settings +❌ Approve mode +❌ Message Deletion settings +❌ Topics settings +❌ Banned words +❌ Recurring messages +❌ Members management +❌ Masked users settings +❌ Discussion group settings +❌ Personal commands +❌ Magic Strickers/GIFs +❌ Max message length settings +❌ Log channel +❌ Staff group +❌ Group statistics +✅ General commands permissions editor +✅ Remove user-data from group (/forget) +❌ Remove user-data from bot +❌ User privacy mode +✅ Crypto prices external api +``` + +## Updating + +To update LibreGroupHelp you need to backup ./database folder and ./config.json, then repeat installation process and paste there again both file and folder, you may need to add some config.json parameters manually if has been added + +## Contribute + +[Documentation](../documentation/) is the section you are looking for if you want to contribute to LibreGroupHelp + +## Ask a question + +If you have any questions about LibreGroupHelp, feel free to open an issue or ask directly in our telegram group [@LGHChat](https://t.me/LGHChat). diff --git a/docs/plugins/antiflood.md b/docs/plugins/antiflood.md new file mode 100644 index 0000000..bf14a0e --- /dev/null +++ b/docs/plugins/antiflood.md @@ -0,0 +1,12 @@ +# Anti Flood + +**File**: `antiflood.js` + +**Description**: Plugin to punish users who send messages on a group too fast, configuration accessible on [settings](settings.md) + + +## Objects implemented + +- **[LGHFlood](../documentation/GHBot.md/#LGHFlood)** +**Use cases**: +[LGHChat](../documentation/GHBot.md#LGHChat).flood diff --git a/docs/plugins/antispam.md b/docs/plugins/antispam.md new file mode 100644 index 0000000..c349e14 --- /dev/null +++ b/docs/plugins/antispam.md @@ -0,0 +1,12 @@ +# Anti Spam + +**File**: `antispam.js` + +**Description**: Plugin to punish users who send spam messages on a group, this may include `quotes`, `forward`, `external links`, and `telegram links`, configuration accessible on [settings](settings.md) + + +## Objects implemented + +- **[LGHSpam](../documentation/GHBot.md/#LGHSpam)** +**Use cases**: +[LGHChat](../documentation/GHBot.md#LGHChat).spam diff --git a/docs/plugins/captcha.md b/docs/plugins/captcha.md new file mode 100644 index 0000000..d091fd7 --- /dev/null +++ b/docs/plugins/captcha.md @@ -0,0 +1,12 @@ +# Captcha + +**File**: `captcha.js` + +**Description**: Plugin to prevent bot fake users from joining the group asking a captcha process to be not punished, configuration accessible on [settings](settings.md) + + +## Objects implemented + +- **[LGHCaptcha](../documentation/GHBot.md/#LGHCaptcha)** +**Use cases**: +[LGHChat](../documentation/GHBot.md#LGHChat).captcha diff --git a/docs/plugins/command-perms.md b/docs/plugins/command-perms.md new file mode 100644 index 0000000..a7dfd14 --- /dev/null +++ b/docs/plugins/command-perms.md @@ -0,0 +1,7 @@ +# Command permissions + +**File**: `api/editors/CommandsPerms.js` + +**Description**: Implements an [editor](../documentation/editors.md) menu to change commands on a [permissions](../documentation/GHBot.md/#lghperms-object) Object, + +Allows also to set up both permissions for user with private/group reply, and admin with private/group reply, in future it may be used to change perms for roles \ No newline at end of file diff --git a/docs/plugins/goodbye.md b/docs/plugins/goodbye.md new file mode 100644 index 0000000..192fbb9 --- /dev/null +++ b/docs/plugins/goodbye.md @@ -0,0 +1,12 @@ +# Goodbye + +**File**: `goodbye.js` + +**Description**: Plugin to send a goodbye on private user chat and in the group when an user leaves, you can edit both trough [settings](settings.md) with [MessageMaker](message-maker.md) + + +## Objects implemented + +- **[LGHGoodbye](../documentation/GHBot.md/#LGHGoodbye)** +**Use cases**: +[LGHChat](../documentation/GHBot.md#LGHChat).goodbye diff --git a/docs/plugins/index.md b/docs/plugins/index.md new file mode 100644 index 0000000..4f965da --- /dev/null +++ b/docs/plugins/index.md @@ -0,0 +1,5 @@ +# Plugins documentation + +Here you can find every documentation about any [plugin](../documentation/plugins.md) and [editors](../documentation/editors.md) + +Use left side panel to navigate \ No newline at end of file diff --git a/docs/plugins/message-maker.md b/docs/plugins/message-maker.md new file mode 100644 index 0000000..47546fb --- /dev/null +++ b/docs/plugins/message-maker.md @@ -0,0 +1,90 @@ +# Message maker + +## Informations + +**File**: `api/editors/MessageMaker.js` + +**Description**: This is an [editor](../documentation/editors.md) who adds a panel to allow an user to configurate easly a message with `text`, `media` and `buttons`, then, using `MessageMaker.sendMessage` function you can send it anywhere + +### Substitutions + +It implements also a text substitution system extended optionally trough `config.allowExternalApi`, the substitutions are as follows: + + • {ID} = user ID + + • {NAME} = first name of user + + • {SURNAME} = user surname + + • {NAMESURNAME} = name and surname + + • {GHNAME} = name in LGH format ( [userId] name/surname ) + + • {USERNAME} = user @username + + • {MENTION} = link to the user profile + + • {LANG} = user language + + • {FLAG} = user language flag + + • {GROUPNAME} = group name + + • {GROUPUSERNAME} = group username + + • {GROUPID} = group id + + --- + + config.allowExternalApi substitutions: + + Syntax: FIAT{SYMBOL:OPTION} + + • {BTC} {ETH} {BNB} {SOL} {XRP} {DOGE} {TON} {ADA} ... {XMR} = crypto price, avaiable any top2000 crypto symbol + + • {TOP1} {TOP2} ... {TOP2000} = get crypto symbol at specific classific height (max 2000) ({TOP1} will translate to "BTC", so {{TOP1}} is the same of {BTC} and will give you the crypto price) + + • Options: CAP(capitalization), VOL(24h volume), SUPPLY, RANK(cap classific), NAME, EXPLORER. (example: {BTC:CAP}) + + • Convert from default to specific currency: ${number}, €{number}, £{number}, CHF{number} or ₣{number}. + + • Examples: {BNB}, €{BTC}, CHF{ETH}, £{BTC:CAP}, {XMR:SUPPLY}, €{{TOP15}} £{{TOP3}:NAME} + + • Api: https://api.coincap.io/v2/assets (https://docs.coincap.io/) + + + --- + + NOT IMPLEMENTED: + + • {RULES} = group regulation text + + • {DATE} = current date + + • {TIME} = current time + + • {WEEKDAY} = week day + + • {MONTH} = current month + + • {YEAR} = current year + + • {UNIX} = seconds since 1970/1/1 + + + + +## Objects implemented + +- **[customMessage](../documentation/GHBot.md/#custommessage-object)** +**Use cases**: +[LGHChat](../documentation/GHBot.md/#LGHChat).rules +[LGHWelcome](../documentation/GHBot.md/#lghwelcome-object).message +[LGHGoodbye](../documentation/GHBot.md/#LGHGoodbye).gMsg +[LGHGoodbye](../documentation/GHBot.md/#LGHGoodbye).pMsg + +
+ +- **[simpleMedia](../documentation/GHBot.md/#simplemedia-object)** +**Use cases**: +[customMessage](../documentation/GHBot.md/#LGHChat).media \ No newline at end of file diff --git a/docs/plugins/pin.md b/docs/plugins/pin.md new file mode 100644 index 0000000..f13681e --- /dev/null +++ b/docs/plugins/pin.md @@ -0,0 +1,7 @@ +# Pin + +**File**: `pin.js` + +**Description**: Plugin to add pin messages commands + +**Commands**: `/pin` \ No newline at end of file diff --git a/docs/plugins/promote.md b/docs/plugins/promote.md new file mode 100644 index 0000000..e06347b --- /dev/null +++ b/docs/plugins/promote.md @@ -0,0 +1,7 @@ +# Promotions + +**File**: `promotions.js` + +**Description**: This plugin add commands to promote users to any pre-made role by [Roles manager](roles-manager.md) + +**Commands**: `/free`, `/unfree`, `/helper`, `/unhelper`, `/cleaner`, `/uncleaner`, `/muter`, `/unmuter`, `/mod`, `/unmod`, `/cofounder`, `/uncofounder`, `/admin`, `/unadmin`, `/title`, `/untitle` \ No newline at end of file diff --git a/docs/plugins/punish.md b/docs/plugins/punish.md new file mode 100644 index 0000000..6fcfc03 --- /dev/null +++ b/docs/plugins/punish.md @@ -0,0 +1,7 @@ +# Punishments + +**File**: `punish.js` + +**Description**: Implement punishent and unpunishent commands using the utility of `api/utils/punishment.js` + +**Commands**: `/delete`, `/warn`, `/unwarn`, `/kick`, `/mute`, `/unmute`, `/ban`, `/unban` \ No newline at end of file diff --git a/docs/plugins/roles-manager.md b/docs/plugins/roles-manager.md new file mode 100644 index 0000000..ef38c82 --- /dev/null +++ b/docs/plugins/roles-manager.md @@ -0,0 +1,35 @@ +# Roles Manager + +## Informations + +**File**: `usersHandler.js` + +**Description**: This plugin manage users data and roles in the group, implements also `api/utils/rolesManager.js` to give an external interface to deal with roles + +Adds on `global.roles[roleName]` data about these pre-made roles: `founder`, `moderator`, `muter`, `cleaner`, `helper`, `free`. + +**Commands**: `/reload`, `/staff`, `/info`, `/perms`, `/forgot` + + +## Objects implemented + +- **[LGHRole](../documentation/GHBot.md/#lghrole-object)** +**Use cases**: +[LGHChat](../documentation/GHBot.md#LGHChat).roles + +
+ +- **[LGHPerms](../documentation/GHBot.md/#lghperms-object)** +**Use cases**: +[LGHChat](../documentation/GHBot.md#LGHChat).basePerms +[LGHChat](../documentation/GHBot.md#LGHChat).adminPerms +[LGHUser](../documentation/GHBot.md#LGHUser).perms +[LGHRole](../documentation/GHBot.md#LGHRole).perms + +
+ +- **[userStatus](../documentation/GHBot.md/#userstatus-object)** +**Use cases**: +[LGHChat](../documentation/GHBot.md#LGHChat).users + +
diff --git a/docs/plugins/rules.md b/docs/plugins/rules.md new file mode 100644 index 0000000..8ed47bf --- /dev/null +++ b/docs/plugins/rules.md @@ -0,0 +1,7 @@ +# Rules + +**File**: `rules.js` + +**Description**: Plugin to add rules of the group and allow to edit these trough [settings](settings.md) with [MessageMaker](message-maker.md) + +**Commands**: `/rules` \ No newline at end of file diff --git a/docs/plugins/set-chat-based-punish.md b/docs/plugins/set-chat-based-punish.md new file mode 100644 index 0000000..ec8c2a5 --- /dev/null +++ b/docs/plugins/set-chat-based-punish.md @@ -0,0 +1,17 @@ +# Set chat based punishment + +## Informations + +**File**: `api/editors/setChatBasedPunish.js` + +**Description**: This is an [editor](../documentation/editors.md) who adds a panel to allow an user to configurate easly a different punishment based on various chat types `private`, `bot`, `group`, `channel` + + +## Objects implemented + +- **[LGHChatBasedPunish](../documentation/GHBot.md/#lghrole-object)** +**Use cases**: +[LGHSpam](../documentation/GHBot.md/#lghspam-object).forward +[LGHSpam](../documentation/GHBot.md/#lghspam-object).quote + +
\ No newline at end of file diff --git a/docs/plugins/settings.md b/docs/plugins/settings.md new file mode 100644 index 0000000..6d01a33 --- /dev/null +++ b/docs/plugins/settings.md @@ -0,0 +1,7 @@ +# Settings + +**File**: `settings.js` + +**Description**: This plugin manages settings for single users and settings panel for groups, lang settings are included + +**Commands**: `/settings` \ No newline at end of file diff --git a/docs/plugins/warns.md b/docs/plugins/warns.md new file mode 100644 index 0000000..dfcdcfc --- /dev/null +++ b/docs/plugins/warns.md @@ -0,0 +1,12 @@ +# Warns + +**File**: `warns.js` + +**Description**: Plugin to implement warn configuration [settings](settings.md) on a group + + +## Objects implemented + +- **[LGHWarns](../documentation/GHBot.md/#LGHWarns)** +**Use cases**: +[LGHChat](../documentation/GHBot.md#LGHChat).warns diff --git a/docs/plugins/welcome.md b/docs/plugins/welcome.md new file mode 100644 index 0000000..5496b78 --- /dev/null +++ b/docs/plugins/welcome.md @@ -0,0 +1,12 @@ +# Welcome + +**File**: `welcome.js` + +**Description**: Plugin to allow to set up trough [settings](settings.md) with [MessageMaker](message-maker.md) a welcome message for new users in the group + + +## Objects implemented + +- **[LGHWelcome](../documentation/GHBot.md/#lghwelcome-object)** +**Use cases**: +[LGHChat](../documentation/GHBot.md#LGHChat).welcome diff --git a/docs/wiki/commands.md b/docs/wiki/commands.md new file mode 100644 index 0000000..d1f641e --- /dev/null +++ b/docs/wiki/commands.md @@ -0,0 +1,172 @@ +# 📋 Commands + +> ### Note for devs: +> - **`COMMAND_`** code prefix means that the command is to be resolved on languages. +> - **`COMMAND`** codes is also used to define permitted commands on [perms](../documentation/GHBot.md/#LGHPerms) object. +> - **`@`** prefix on a command code/name means that user has permission to get the reply within private chat only (e.g., `@COMMAND_RULES`). + +--- + +Some commands can use the **`*`** prefix (e.g., `/*rules`, `/*perms`) to force a reply on private chat, only if you have the right permissions inside the group + +### General Commands + +- **/settings** + Opens the group settings. + **Code:** `COMMAND_SETTINGS` + +- **/rules** + Shows the group rules. + **Code:** `COMMAND_RULES` + **Note:** **`*`** Allowed + +- **/perms** + Shows bot permissions of a user. + **Code:** `COMMAND_PERMS` + **Note:** **`*`** Allowed + +- **/staff** + Shows group staff with default and custom roles. + **Code:** `COMMAND_STAFF` + **Note:** **`*`** Allowed + +- **/info** + Shows information about a group user and allows editing. + **Code:** `COMMAND_INFO` + **Note:** **`*`** Allowed + +- **/me** + Shows information about yourself. + **Code:** `COMMAND_ME` + **Note:** **`*`** Allowed + +- **/pin** + Pins a chat message with or without a notification. + **Code:** `COMMAND_PIN` + **Note:** **`*`** Allowed + +### Punishment Commands + +- **/del** + Deletes a message. + **Code:** `COMMAND_DELETE` + +- **/warn** + Warns a user and punishes them if they reach the group warning limit. + **Code:** `COMMAND_WARN` + +- **/unwarn** + Removes a warning from a user. + **Code:** `COMMAND_UNWARN` + +- **/delwarn** + Warns a user and deletes a message. + **Code:** `COMMAND_DELWARN` + +- **/kick** + Kicks a user out of the group. + **Code:** `COMMAND_KICK` + +- **/delkick** + Kicks a user and deletes a message. + **Code:** `COMMAND_DELKICK` + +- **/mute** + Disables messaging for a user. + **Code:** `COMMAND_MUTE` + +- **/unmute** + Re-enables messaging for a user. + **Code:** `COMMAND_UNMUTE` + +- **/delmute** + Mutes a user and deletes a message. + **Code:** `COMMAND_DELMUTE` + +- **/ban** + Permanently removes a user from the group. + **Code:** `COMMAND_BAN` + +- **/unban** + Unbans a user from the group. + **Code:** `COMMAND_UNBAN` + +- **/delban** + Bans a user and deletes a message. + **Code:** `COMMAND_DELBAN` + +### Role Management Commands + +- **/free** + Assigns the free role to a user. + **Code:** `COMMAND_FREE` + +- **/unfree** + Removes the free role from a user. + **Code:** `COMMAND_UNFREE` + +- **/helper** + Assigns the helper role to a user. + **Code:** `COMMAND_HELPER` + +- **/unhelper** + Removes the helper role from a user. + **Code:** `COMMAND_UNHELPER` + +- **/cleaner** + Assigns the cleaner role to a user. + **Code:** `COMMAND_CLEANER` + +- **/uncleaner** + Removes the cleaner role from a user. + **Code:** `COMMAND_UNCLEANER` + +- **/muter** + Assigns the muter role to a user. + **Code:** `COMMAND_MUTER` + +- **/unmuter** + Removes the muter role from a user. + **Code:** `COMMAND_UNMUTER` + +- **/mod** + Assigns the moderator role to a user. + **Code:** `COMMAND_MODERATOR` + +- **/unmod** + Removes the moderator role from a user. + **Code:** `COMMAND_UNMODERATOR` + +- **/cofounder** + Assigns the cofounder role to a user. + **Code:** `COMMAND_COFOUNDER` + +- **/uncofounder** + Removes the cofounder role from a user. + **Code:** `COMMAND_UNCOFOUNDER` + +### Admin Commands + +- **/admin** + Grants admin status to a user. + **Code:** `COMMAND_ADMINISTRATOR` + +- **/unadmin** + Removes admin status from a user. + **Code:** `COMMAND_UNADMINISTRATOR` + +- **/title** + Sets an administrator group title. + **Code:** `COMMAND_TITLE` + +- **/untitle** + Removes an administrator group title. + **Code:** `COMMAND_UNTITLE` + +### Privacy Commands + +- **/forgot** + Removes all data about an user from your group. + **Code:** `COMMAND_FORGOT` + +
\ No newline at end of file diff --git a/docs/wiki/configuration.md b/docs/wiki/configuration.md new file mode 100644 index 0000000..7712724 --- /dev/null +++ b/docs/wiki/configuration.md @@ -0,0 +1,71 @@ +# Configuration guide (config.json) + +## Essential settings + +**botToken**: `String` +Your bot token gaven from [@BotFather](https://t.me/BotFather) (ex. `4839574812:AAFD39kkdpWt3ywyRZergyOLMaJhac60qc`) + +**botStaff**: `Array` +List of User Ids considered bot staff (ex. `[33224765, 82399935]`) + + +## Privacy settings + +**deleteChatDataAfterBotRemove**: `Boolean` +If enabled all chat data will be deleted from bot database when you kick the bot from a group + +**overwriteChatDataIfReAddedToGroup**: `Boolean` +If enabled chat data and configurations will be regenerated if bot has been re-added to the group overwriting the old one + +**allowExternalApi**: `Boolean` +Allow to gather additional data by various online api's, that's may reveal the ip of your server, default to false + + +## Other settings + +**reserveLang**: `String` +Main bot language, this will be used to overwrite other languages with incompleted translations, we advise to keep it unchanged or use a full implemented language + +**saveDatabaseSeconds**: `Number` +Number of seconds of how often loaded chats should be written on disk, useful to prevent data loss on crash + +**saveTagResolverSeconds**: `Number` +Number of seconds of how often tagResolver data should be saved on disk + +**maxCallbackAge**: `Number` +Maximum number of seconds a callback button should be old to be accepted by the bot, you can reduce this in case of incompatible callbacks after an update that cause crash + +**preventSetUselessRoles**: `Boolean` +Disallow from setting roles if it does not change the user status in the group + +**chatWhitelist**: `Array` +If there are at least one element the bot will work only on these chat ids (ex. `[-10294995433434, -429930035587]`) + +**privateWhitelist**: `Boolean` +True if chat whitelist should ignore also private chats not included in chatWhitelist, useless if chatWhitelist is disabled + +**chatBlacklist**: `Array` +Bot wont more handle requests of Chat Ids on this list (ex. `[-10294995433434, -429930035587]`) + + +## Plugin settings + +**ANTIFLOOD_msgMin**: `Number` +minimum settable number of messages to triggher the antiflood + +**ANTIFLOOD_msgMax**: `Number` +maximum settable number of messages to triggher the antiflood + +**ANTIFLOOD_timeMin**: `Number` +minimum settable time in which N messages should be sent to triggher the antiflood + +**ANTIFLOOD_timeMax**: `Number` +maximum settable time in which N messages should be sent to triggher the antiflood + +**minWarns**: `Number` +minimum settable warns on settings + +**maxWarns**: `Number` +maximum settable warns on settings + +
\ No newline at end of file diff --git a/docs/wiki/perms.md b/docs/wiki/perms.md new file mode 100644 index 0000000..28e46ee --- /dev/null +++ b/docs/wiki/perms.md @@ -0,0 +1,46 @@ +# Permissions + +Permissions is the system that define what the user is allowed or disallowed to do inside your group, what commands he can and can't use, and trough [roles](roles.md) authority level, who he can penalize and who not + +An user inherits the autorithy level from the higher level among his roles + +You can always see the permissions and level that an user owns using `/perms` + +--- + +## Calculating user permissions + +The calculation of user permissions is made by levels of priority based on this order (the following list goes from lowest priority to higher): + + +- **👥 Group basic permissions** + The basic group permissions that's applied by default to every user, that has lowest priority on perms calculation + **🔧 How to edit:** `/settings` -> `Other (button)` -> `Permissions` -> `Commands permissions` +

+ +- **👲 Admin basic permissions** + Basic group permissions that's applied to every group administrator + **🔧 How to edit:** `/settings` -> `Other (button)` -> `Permissions` -> `Commands permissions` +

+ +- **🎓 Roles permissions** + Permission set of each [role](roles.md/#bot-roles), priority ordered from lowest role Authority level to higher + **🔧 How to edit:** [Bot roles promotion commands](roles.md/#bot-roles) +

+ +- **👮 Admin permissions** + Permissions inhered from administrator telegram settings, if an admin can do an action trough telegram, he will be able to do so also trough LibreGroupHelp + **🔧 How to edit:** `/admin`, `/perms` or telegram settings +

+ +- **👤 User permissions** + Permission applyed only to that one specific user, it takes over maximum priority on perms calculation, essential for more granular permissions control + **🔧 How to edit:** Currently not implemented +

+ + +Each permission can be either ✅ allowing wise, 🔘 neutral, or ❌ disallowing wise, as example, if `Group basic permissions` (lowest priority) allows the `/rules` command, but `User permissions` (highest priority) disallow it, this user won't be able to use `/rules` + +Neutral state instead, allows an higher priority level to inherit from lowest, when creating custom roles we advise you to use always the neutral state if the role you are making is not limitation-focused + +
\ No newline at end of file diff --git a/docs/wiki/roles.md b/docs/wiki/roles.md new file mode 100644 index 0000000..1d2519f --- /dev/null +++ b/docs/wiki/roles.md @@ -0,0 +1,87 @@ +# Roles + +You can set roles to every user on your group, the main use of roles is giving an user authority level on the group and give them a defined set of [permissions](perms.md), both relative to your group and bot + +You can see what roles are assigned to users on your group using `/staff` + +## Admin role + +The most important role is the [Administrator](https://telegram.org/blog/supergroups) role, an user can get this role with `/admin` command (advised) or [directly trough your group settings](https://telegram.org/blog/admin-revolution#admin-rights), by fact it's the role directly correlated with the acutal admin from telegram side, you can change admin title using `/title` + +LibreGroupHelp will bind the telegram admin permissions to match with the correlated commands and functions + +If for example by telegram settings your admin can remove users, he will automatically obtain this LibreGroupHelp commands: `/kick`, `/warn`, `/mute`, `/ban` + +--- + +## Bot roles + +LibreGroupHelp aims to provide a more granular control about permissions of your users and staffers, a granularity that trough telegram admins function can't be reached, that's why you can give the role `/muter` to allow a staffer to use just the `/mute` command, + +Currently these are the roles implemented by LibreGroupHelp: + +- **👑 Founder** + The role avaiable only for group owner + **Commands:** `All` + **Promotion:** Telegram settings (transfer ownership) + **🔏 Bot permissions:** `All` + **📗 Authority:** 100 +

+ +- **⚜️ Co-Founder** + The role to give full bot permissions to an user + **Commands:** `All` + **Promotion:** `/cofounder`, `/uncofounder` + **🔏 Bot permissions:** `All` + **📗 Authority:** 90 +

+ +- **👮 Administrator** + The role given to every group admin on telegram + **Commands:** Depends on admin permissions + **Promotion:** [Telegram settings](https://telegram.org/blog/admin-revolution#admin-rights) + **🔏 Bot permissions:** `immune`, `flood`, `spam`, `nsfw`, `night`, `media`, `alphabets`, `words`, `length` (for `roles` and `settings` depends on telegram admin permissions) + **📗 Authority:** 0 +

+ +- **🙊 Muter** + Staffer who can mute users + **Commands:** `/rules`, `/mute`, `/unmute` + **Promotion:** `/muter`, `/unmuter` + **🔏 Bot permissions:** none + **📗 Authority:** 40 +

+ +- **🛃 Cleaner** + Staffer who can delete messages from your group + **Commands:** `/rules`, `/delete` + **Promotion:** `/cleaner`, `/uncleaner` + **🔏 Bot permissions:** none + **📗 Authority:** 20 +

+ +- **⛑ Helper** + An user that contributes to the group support + **Commands:** `/rules`, `/info` + **Promotion:** `/helper`, `/unhelper` + **🔏 Bot permissions:** none + **📗 Authority:** 10 +

+ +- **🔓 Free** + An user free from any bot restriction + **Commands:** none + **Promotion:** `/free`, `/unfree` + **🔏 Bot permissions:** `immune`, `flood`, `spam`, `nsfw`, `night`, `media`, `alphabets`, `words`, `length` + **📗 Authority:** 0 + + +--- + +## Custom roles + +Custom roles is a functionality still not implemented and we aim to add as soon as possible, the priority depends from the acutal request from users + +Custom roles will unlock you the possibility to create your own group roles with any Role Level and any permission set you want, speeding up your administration work + +
diff --git a/documentation.md b/documentation.md deleted file mode 100644 index 9ff15a1..0000000 --- a/documentation.md +++ /dev/null @@ -1,248 +0,0 @@ -## General code info - -index.js does load every plugin and database and acutal bot on main.js - -main.js does all necessary works before emitting on GHbot and event with many LibreGroupHelp related data ready to use - -all data is managed by database.js, you can access it's methods from db.chats and db.users - -all jsdocs objects documentation is on GHbot.js, it's also essential to document event parameters of GHbot events - -use TGbot only if you need direct native access with telegram bot api, when possible you should use GHbot events and methods and if does not exhist the one needed create that, TGbot method docs can be found on https://github.com/yagop/node-telegram-bot-api, on TGbot.me is avaiable await TGbot.getMe() result - -While coding keep in mind that user should be able to delete his data in any moment, this for respecting the privacy philosophy of LibreGroupHelp (exception can be for essential data for groups, for example warns number, allow to delete this is going to be abusable) - -## Plugins - -Look at example.js plugin to see how it uses right functions and methods to work with LibreGroupHelp - -```javascript -var LGHelpTemplate = require("../GHbot.js") - -function main(args) -{ - - const GHbot = new LGHelpTemplate(args); - const {TGbot, db, config} = GHbot; - - //here your plugin code// - - l = global.LGHLangs; //importing langs object - - GHbot.onMessage( (msg, chat, user) => { - - if( chat.type == "private" && msg.text == "/test999" ) - GHbot.sendMessage( user.id, chat.id, "Hello, i send this because im a plugin\n"+l[user.lang].flag ); - - } ) - - -} - -module.exports = main; -``` - - -You can create and use functions to import on ./api/, but if you think it's going to be used only on your plugin you can do that in same file -If you need access text of varius languages it's stored at global.LGHLangs (I advise set it like this "l = global.LGHLangs;") - - -## GHBot variables - -ONLY for events from GHBot you have additional elements on parameters bot-related - -Usually GHBot events has 3 parameters: request (cb/msg), chat, user. - -On GHBot.onCallback() and GHBot.onMessage() if event comes from a group or callback data has a chat id, "chat" object will contain the full Custom Chat Object with chat.isGroup true, anyway the chat from where the request is coming is always avaiable in cb.chat or msg.chat - -user.perms (result of api/rolesManager/sumUserPerms()) is avaiable in 2 cases: if callback.data or msg.waitingReply contains a groupId, if cb.chat.isGroup or msg.chat.isGroup - -NOTE: user.perms is a temporary item, it's not intended to be saved in the database (database does not save it) -Any "msg" object contains msg.command (result of api/utils/parseCommand(msg.text)) - -Targets -Any message object may contain an msg.target object if a message reply target user is found -Also cb.target may exhist, builded up from user id after "?" in cb.data -msg.waitingReplyTarget is set if a target if found on msg.waitingReplyType (after "?") - -NOTE FOR CALLBACK EVENT: callback event gives you the full chat object only if chat.isGroup is true, if is private chat you should require it yourself from the database (var settingsChatId = cb.data.split(":")[1]; var settingsChat = db.chats.get(settingsChatId)) - -You can find a comment referring security guards that you can use too in plugins/welcome.js - - -## Language info - -The bot has a different language configuration both for users and group -when LibreGroupHelp is added to a group (and add it to the database) the default group language will be inherited from the user who added the bot, (TODO. convert function for telegram user.language_code to LibreGroupHelp lang code, format on https://en.wikipedia.org/wiki/IETF_language_tag) - - -## Expect user messages - -You can expect for user messages in a chat or in private for a chat by using waitReplyForChat(db, callback, user, chat, onGroup) (from utils.js) -The text on callback variable should follow the Callbacks LGH Hirarchy (hirarchy in the section below) - -When you receive a new message event msg.waitingReply will be set to string or false by main.js depending if it's the right chat -Remember that if you waitReplyForChat in a certain point you will need also to disable that, otherwise other bot functions that wants msg.waitingReply false is not going to work (like commands), disable with unsetWaitReply(db, user, chat, onGroup) - - -## Callbacks and user callbacks data management (Hirarchy) - -Here is described the hirarchy of callbacks data. -Giving right callaback data is essential to allow main.js to pre-set wanted values -They are both avaiable on cb.data for buttons or on msg.waitingReplye for messages that bot is expecting - -Hirarchy - -cb.data OR msg.waitingReply = CALLBACK_NAME!data#editor_things|editorData:groupId?targetUserId - -To work with less items, same order only matters: CALLBACK_NAME:groupId OR CALLBACK_NAME#editor?targetUserId OR CALLBACK_NAME:groupId?targetUserId. They are all valid - --CALLBACK_NAME: name of callback that you can use, be sure that not conflicts with other names, often plugins check if it's their match with string.startsWith() - --data: some additional data that you can attach to CALLBACK_NAME - --editor: also that is often identified with string.startsWith(), it's usually used to open re-usable menus like MessageMaker.js, setNum.js, setTime.js - --editorData that editor may attach - --groupId: that allow main.js to set a full object of chat (note: msg.chat or cb.message.chat may be not affected, GHbot ever gives you a dedicated chat parameter), it also allow to set the user.perms object in private chat (in group it's done directly from chat.id) - --targetUserId: that allow main.js to set a target user in various cases: cb.target, msg.userWaitingReplyTarget (target for text commands is not related with that, it's also avaiable on msg.target and it's based on msg.text instead of targetUserId) - - -## Roles - -Roles is managed by plugins/usersHandler.js and api/rolesManager.js - -An user can have multiple roles at the same time -Every role has a level, higher level means best role priority, an user inherits the level of the higher level on its roles -An user can affect with any allowed command any other user with a level lower than him - -Both users and roles has their own customPerms object, user perms object has the maximal priority -(rolesManager.js) sumUserPerms() will sum for you all permissions, including roles ordered by level and user perms itself with maximum priority, this function is all you need to know what the user can and can't do - -Pre-made roles are set with specific commands (/mod, /muter, /cleaner, /helper, /free) +(unset with "un" prefix, ex: "/unmod") -To set custom roles the command will be /setrole roleName - -User permissions data result of sumUserPerms() may be avaiable at target.perms or user.perms - - -## LGH Objects - -Custom Chat Object - -Additional data of custom chat object: - ->admins: array with known admins objects (user data anonymized) - ->lang : current chat lang - ->isGroup : result of (chat.type == "supergroup" || chat.type == "group") - ->users : Object-IdName based data about every user in the group (ex. users[643547] access data of userId 643547) - ->basePerms : base permissions applyed to every user - ->adminPerms : base permissions applyed to admin - ->roles : GHRole data about a specific role, full role Object if it's a custom role (key with a number) - ->warns : warns.js plugin related data - ->rules : rules.js plugin related data - ->welcome : welcome.js plugin related data - ->flood : flood.js plugin related data - --When you modify any of this data don't forget to update it with db.chats.update(chat) - - -Custom User Object - -Additional data of custom user object: - ->lang : current user lang - ->waitingReply : set to true if the bot is expecting a message from the user - --When you modify any of this data don't forget to update it with db.users.update(user) - - -Custom Message Object - -Additional data of custom msg object: - ->command : result of message text parsed with parseCommand() - ->target : identified target of message, it's may be derived from the command or from replyed user - - -Command Object - -You can get this object trough parseCommand(text) - * @property {String} text - Full raw command text - * @property {String} prefix - Prefix, example: / ! . , ; - * @property {String} botCommand - Command and bot specifier (ex. "start@usernamebot") - * @property {String} name - Command name (ex. "start") - * @property {String} bot - Specified bot name (ex. "usernamebot") - * @property {String} args - Raw arguments text after the command - * @property {Array} splitArgs - Array of arguments split by space - -*target is not listed because that's set later by main.js - - -## Commands - -Note: COMMAND_ prefix means that command can be solved in multiple languages -@ prefix in command name gives the permission with private chat reply (example @COMMAND_RULES) -to explicitly ask to reply to your command in private chat use * as prefix (ex. /\*rules, /\*perms) -Complete list of implemented commands: - --General -* /settings - open group settings (COMMAND_SETTINGS) -* /rules - show group rules (COMMAND_RULES) (force private avaiable) -* /perms - show bot permissions of an user (COMMAND_PERMS) (force private avaiable) -* /staff - show group staff with default and custom roles (COMMAND_STAFF) (force private avaiable) -* /info - show info about a group user and edit it (COMMAND_INFO) (force private avaiable) -* /me - show info about yourself (COMMAND_ME) (force private avaiable) -* /pin - pin a chat message with or without notification (COMMAND_PIN) (force private avaiable) - --Punishments -* /del - delete a message (COMMAND_DELETE) -* /warn - warn user and punish if reach group warn limit (COMMAND_WARN) -* /unwarn - remove a warn from user (COMMAND_UNWARN) -* /delwarn - warn user and delete a message (COMMAND_DELWARN) -* /kick - kick an user out from the group (COMMAND_KICK) -* /delkick - kick user and delete a message (COMMAND_DELKICK) -* /mute - disable messages to a user (COMMAND_MUTE) -* /unmute - re-enable messages to an user (COMMAND_UNMUTE) -* /delmute - mute user and delete a message (COMMAND_DELMUTE) -* /ban - permanently remove an user from the group (COMMAND_BAN) -* /unban - unban user from the group (COMMAND_UNBAN) -* /delban - ban user and delete a message (COMMAND_DELBAN) - --Roles -* /free - give free role to user (COMMAND_FREE) -* /unfree - remove free role to user (COMMAND_UNFREE) -* /helper - set helper role to user (COMMAND_HELPER) -* /unhelper - remove helper role to user (COMMAND_UNHELPER) -* /cleaner - set cleaner role to user (COMMAND_CLEANER) -* /uncleaner - remove cleaner role to user (COMMAND_UNCLEANER) -* /muter - set muter role to user (COMMAND_MUTER) -* /unmuter - remove muter role to user (COMMAND_UNMUTER) -* /mod - set moderator role to user (COMMAND_MODERATOR) -* /unmod - remove moderator role to user (COMMAND_UNMODERATOR) -* /cofounder - set cofounder role to user (COMMAND_COFOUNDER) -* /uncofounder - remove cofounder role to user (COMMAND_UNCOFOUNDER) - --Admins -* /admin - make user admin (COMMAND_ADMINISTRATOR) -* /unadmin - remove admin role to user (COMMAND_UNADMINISTRATOR) -* /title - set admin title (COMMAND_TITLE) -* /untitle - remove admin title (COMMAND_UNTITLE) - --Privacy -* /forgot - remove every data on the group about an user (COMMAND_FORGOT) - -You can find additional info on plugins.md https://github.com/Sp3rick/GroupHelp/blob/main/plugins.md diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..f58290f --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,80 @@ +site_name: LibreGroupHelp Wiki +site_url: https://sp3rick.github.io/GroupHelp +repo_url: https://github.com/Sp3rick/GroupHelp +repo_name: Sp3rick/GroupHelp + +theme: + name: material + logo: assets/logo.png + palette: + - scheme: default + primary: deep purple + accent: green + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - scheme: slate + primary: deep purple + accent: green + toggle: + icon: material/brightness-4 + name: Switch to light mode + features: + - search.suggest + - search.highlight + - search.share + - navigation.tabs + - navigation.tabs.sticky + - navigation.indexes + - content.code.copy + +nav: + - Home: + - Home: index.md + - Configuration: wiki/configuration.md + - Commands: wiki/commands.md + - Roles: wiki/roles.md + - Permissions: wiki/perms.md + - Documentation: + - Home: documentation/index.md + - Plugins creation: documentation/plugins.md + - Database usage: documentation/database.md + - Expect messages/buttons: documentation/callbacks.md + - LGH Events: documentation/events.md + - Command creation: documentation/commands.md + - Languages: documentation/languages.md + - Editors: documentation/editors.md + - Objects: documentation/GHBot.md + - TODO List: documentation/TODO-List.md + - Known issues: documentation/known-issues.md + - Plugins Documentation: + - Home: plugins/index.md + - Settings: plugins/settings.md + - ✏️ Message maker: plugins/message-maker.md + - Roles manager: plugins/roles-manager.md + - Promotions: plugins/promote.md + - Punishments: plugins/punish.md + - Rules: plugins/rules.md + - Welcome: plugins/welcome.md + - Anti-Flood: plugins/antiflood.md + - Anti-Spam: plugins/antispam.md + - Captcha: plugins/captcha.md + - Goodbye: plugins/goodbye.md + - Warns: plugins/warns.md + - Pin: plugins/pin.md + - ✏️ Set chat based punishment: plugins/set-chat-based-punish.md + - ✏️ Command permissions: plugins/command-perms.md + + + + + + +markdown_extensions: + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences diff --git a/package.json b/package.json index 68713b2..4148d1d 100644 --- a/package.json +++ b/package.json @@ -1,4 +1,7 @@ { + "devDependencies": { + "jsdoc-to-markdown": "^8.0.3" + }, "dependencies": { "@xmldom/xmldom": "^0.8.10", "canvas": "^2.11.2", diff --git a/plugins.md b/plugins.md deleted file mode 100644 index 80477df..0000000 --- a/plugins.md +++ /dev/null @@ -1,439 +0,0 @@ -Here there are various documentations about various plugins, if you created one you can document it here - -If you need documentation look at here [documentation.md](https://github.com/Sp3rick/GroupHelp/blob/main/documentation.md) - - -## Roles Manager -(api/rolesManager.js) - ->Depends on api/utils/utils.js - -This plugin manages users data and roles in the group - -1 means true - -0 means neutral - --1 means false - -LGHPerms Object: - ->commands: array of commands, if starts with "COMMAND_" means its to be translated, otherwise is the literal command -> ->immune: active if this user can't receive any punishment (kick/warn/mute/ban) [1/0/-1] -> ->flood: permission to flood messages [1/0/-1] -> ->link: permission to send links [1/0/-1] -> ->tgLink: permission to send telegram links/usernames [1/0/-1] -> ->forward: permission to forward messages from anywhere [1/0/-1] -> ->quote: permission to quote from anywhere [1/0/-1] -> ->porn: bypass porn/gore checks [1/0/-1] -> ->night: bypass any night mode limitation [1/0/-1] -> ->media: bypass any media limitation [1/0/-1] -> ->alphabets: Bypass any alphabets characters limitations [1/0/-1] -> ->words: Bypass banned words limitations [1/0/-1] -> ->length: Bypass message length limitations [1/0/-1] -> ->roles: permission to change roles of lower level users [1/0/-1] -> ->settings: permission to change bot group settings [1/0/-1] - - -Intended permissions anarchy: (if a left-side permission is not neutral overwrites everything in the right side) - -chat.users[id].perms > chat.users[id].adminPerms > chat.roles[role].perms (higher role level has higher priority) > chat.basePerms - - - -chat.users[id] userStatus Object: - ->firtJoin: Unix number of first user join time in seconds, false if unknown -> ->perms: LGHPerms object for all user-specific permissions -> ->adminPerms: LGHPerms object for user permissions if admin -> ->roles: array of user roles, string for pre-made roles, number for custom roles (user-made) -> ->warnCount: number of user warns -> ->title: user administrator title - - - -chat.roles[role] LGHRole Object: ( the pre-made roles are in global.roles[roleName] ) - ->name: role name -> ->emoji: emoji for the role -> ->level: role level, higher level users can use commands that affect lower level users -> ->perms: LGHPerms object applyed at lowest priority on any user in this role -> ->users: array of userId in this role - - - - - -## Message Maker -(api/MessageMaker.js) - ->Depends on api/utils/utils.js - -simpleMedia Object: - ->type : Type of media (audio, photo, video, video_note, animation, sticker, document) or false -> ->fileId : media fileId or false -> ->options : additional options for TelegramBot - - -customMessage Object: - ->text : Text of messsage -> ->entities : Telegram entities of text -> ->format : Boolean, true if message should be formatted (enabled by default), mean that entities should be passed on sendMessage function -> ->media : { type, fileId, thumbnail } -> ->buttons : String, can be transformed in inline_keyboard with parseTextToInlineKeyboard() -> ->buttonsParsed : already parsed buttons ready to use for inline_keyboard - -Callback_data order: - -CallerPrefix#MSGMK:settingsChatId - -CallerPrefix is useful to allow the caller to identify it's own callback (ex. if( cb.data.startsWith(myPrefix) ... )) - -text avaiable substitutions: - -• {ID} = user ID - -• {NAME} = first name of user - -• {SURNAME} = user surname - -• {NAMESURNAME} = name and surname - -• {GHNAME} = name in LGH format ( [userId] name/surname ) - -• {USERNAME} = user @username - -• {MENTION} = link to the user profile - -• {LANG} = user language - -• {FLAG} = user language flag - -• {GROUPNAME} = group name - -• {GROUPUSERNAME} = group username - -• {GROUPID} = group id - -(TO IMPLEMENT & TODO: allow to make a sum of dates and time) - -• {RULES} = group regulation text - -• {DATE} = current date - -• {TIME} = current time - -• {WEEKDAY} = week day - -• {MONTH} = current month - -• {YEAR} = current year - -• {UNIX} = seconds since 1970/1/1 - -optional if configuration allow external api: - -Syntax: FIAT{SYMBOL:OPTION} - -• {BTC} {ETH} {BNB} {SOL} {XRP} {DOGE} {TON} {ADA} ... {XMR} = crypto price, avaiable any top2000 crypto symbol - -• {TOP1} {TOP2} ... {TOP2000} = get crypto symbol at specific classific height (max 2000) ({TOP1} will translate to "BTC", so {{TOP1}} is the same of {BTC} and will give you the crypto price) - -• Options: CAP(capitalization), VOL(24h volume), SUPPLY, RANK(cap classific), NAME, EXPLORER. (example: {BTC:CAP}) - -• Convert from default to specific currency: ${number}, €{number}, £{number}, CHF{number} or ₣{number}. - -• Examples: {BNB}, €{BTC}, CHF{ETH}, £{BTC:CAP}, {XMR:SUPPLY}, €{{TOP15}} £{{TOP3}:NAME} - -• Api: https://api.coincap.io/v2/assets (https://docs.coincap.io/) - - - - - -## setChatBasedPunish.js - ->Depends on api/utils/utils.js ->Depends on api/setTime.js - -A settings panel to edit LGHChatBasedPunish object (avaiable on GHbot.js) - - - - - -## usersHandler.js - ->Depends on api/rolesManager.js ->Depends on api/utils/utils.js - -Adds on global.roles[roleName] data about pre-made roles: founder, moderator, muter, cleaner, helper, free. - -This plugin is made for automatic handling of secondary works about users on chats that's not needed to stay on main.js - -Added commands: /reload, /staff, /info, /perms, /forgot - - - - - -## promote.js - ->Depends on api/rolesManager.js ->Depends on api/utils/utils.js - -Handle promotions and unpromotions commands, allow also to edit single admin perms - -Added commands: /free, /unfree, /helper, /unhelper, /cleaner, /uncleaner, /muter, /unmuter, /mod, /unmod, /cofounder, /uncofounder, /admin, /unadmin, /title, /untitle - - - - - -## punish.js - ->Depends on api/punishments.js ->Depends on api/utils/utils.js - -Handle punish and unpunish commands - -Added commands: /delete, /warn, /unwarn, /kick, /mute, /unmute, /ban, /unban - - - - - -## Settings Plugin - ->Depends on api/utils/utils.js - -Manage settings for single users and settings panel for chats, lang setting is included - -Added commands: /settings - - - - -## CommandsPerms.js - ->Depends on api/utils/utils.js - -A menu to change basic commands permissions for every on group or admins, in future will allow to change perms for roles - - - - - -## Rules Plugin - ->Depends on api/MessageMaker.js ->Depends on api/utils/utils.js - -Module to add rules of the group and allow to edit these trough settings - -Added commands: /rules - -Adds on chat.rules a custom object "customMessage" (Message Maker) - -Note: if format is false or entities unavaiable set message parse_mode to HTML (User should see changing format as switching betheen HTML and Formatted) - - - - - -## Welcome Plugin - ->Depends on api/MessageMaker.js ->Depends on api/utils/utils.js - -Module to allow set up a welcome message for new users in the group - -Adds on chat.welcome a custom object "LGHWelcome" - -LGHWelcome Object: - ->state : true if welcome is enabled (default false) -> ->once : true if should be sent only at first user join (default false) -> ->clean : true if last welcome message on the group should be (default false) -> ->joinList : array cronology of users that joined the group over time -> ->lastWelcomeId : messageId of last welcome message sent, useful if clean is enabled, false if never sent one before -> ->message : customMessage object - - - - - -## Anti-Flood Plugin - ->Depends on api/rolesManager.js ->Depends on api/utils/utils.js ->Depends on api/setNum.js ->Depends on api/setTime.js - -Adds on chat.flood a custom object "LGHFlood" - -LGHFlood Object: - ->messages: number of messages needed to triggher the Antiflood -> ->time: seconds within the specified message should be sent to triggher the Antiflood -> ->punishment: punishment to apply at the user that trigghers the Antiflood [0:off|1:warn|2:kick|3:mute|4:ban] -> ->PTime: avaiable if punishment is set to warn/mute/ban, contains seconds of punishment -> ->delete: true if flooded messages should be deleted - - - - - -## Anti-Spam Plugin - ->Depends on api/punishment.js ->Depends on api/utils/utils.js ->Depends on api/setNum.js ->Depends on api/setExceptions.js ->Depends on api/setChatBasedPunishment.js ->Depends on api/rolesManager.js - -Adds on chat.flood a custom object "LGHSpam" - -LGHSpam Object: - ->tgLinks: rules and exceptions for telegram links considered as spam -> ->links: rules and exceptions for all links considered as spam -> ->forward: rules and exceptions for all forwarded messages considered as spam -> ->quote: rules and exceptions for all quoted messages considered as spam - - - - - -## Captcha Plugin - ->Depends on api/punishment.js ->Depends on api/utils/utils.js ->Depends on api/setTime.js ->Depends on api/MessageMaker.js ->Depends on svg-captcha ->Depends on canvas ->Depends on canvg ->Depends on @xmldom/xmldom ->Depends on node-fetch - -Adds on chat.captcha a custom object "LGHCaptcha" - -LGHSpam Object: - ->state: True if welcome is enabled (default false). -> ->mode: Type of captcha, can be "image" (default "image") -> ->time: Time limit to solve the captcha -> ->once: True if should be sent only at first user join (from welcome.js) (default false). -> ->fails: True if captcha should notify on group that someone failed the captcha (default false). -> ->punishment: Punishment to apply [1:warn|2:kick|3:mute|4:ban]. -> ->PTime: Available if punishment is set to warn/mute/ban, contains seconds of punishment - - - - - -## Goodbye Plugin - ->Depends on api/MessageMaker.js - -Adds on chat.goodbye a custom object "LGHGoodbye" - -LGHSpam Object: - ->group: True if goodbye should be sent on group -> ->clear: True if last goodbye message should be deleted before sending a new one -> ->lastId: messageId of last goodbye message sent on group -> ->gMsg: Goodbye message to send on group -> ->private: True if goodbye should be sent on private chat -> ->pMsg: Goodbye message to send on private chat - - - - - -## warns.js - ->Depends on api/utils/utils.js ->Depends on api/setNum.js ->Depends on api/setTime.js - -Allow you to change warn settings on a group - -chat.warns Warns Object: - ->timed: ([userId]: [endTime, endTime, endTime]) contains necerray data to revoke scheduled warns when time is over -> ->count: ([userId]: number) countains count of warns for each user -> ->limit: number of warns after wich should be applyed a punishment -> ->punishment: punishment when limit is hit [2:kick|3:mute|4:ban] -> ->PTime: avaiable if punishment is set to warn/mute/ban, contains seconds of punishment - - - - - -## pin.js - ->Depends on api/utils/utils.js - -Adds /pin command and handle all related things diff --git a/runDocs.js b/runDocs.js new file mode 100644 index 0000000..18742ea --- /dev/null +++ b/runDocs.js @@ -0,0 +1,24 @@ +const fs = require('fs'); +const jsdoc2md = require('jsdoc-to-markdown'); + +const data = fs.readFileSync("./GHbot.js", "utf-8").replaceAll("&","|"); +const docs = jsdoc2md.renderSync({source: data, "no-cache": true}) +.replaceAll("TelegramBot", "[TelegramBot](https://github.com/yagop/node-telegram-bot-api/blob/master/doc/api.md)") +.replaceAll(`TelegramBot.`, `TelegramBot.`) + +const head = +`## TelegramBot api + +You can finnd documentation about TelegramBot Objects on [telegram-bot-api](https://github.com/yagop/node-telegram-bot-api/blob/master/doc/api.md) github + +--- + +The down below lines are generated with [jsdoc2md](https://github.com/jsdoc2md/jsdoc-to-markdown) + + +` + +fs.writeFileSync("./docs/documentation/GHBot.md", head+docs) + +console.log("JSDoc to Markdown successfull, now run `mkdocs serve`\n"+ + "Install guide for mkdocs: https://www.mkdocs.org/user-guide/installation/")