From 2a53887abba882bf7b63aeda8dfa55fdb3ab8792 Mon Sep 17 00:00:00 2001
From: Sin-MacBook <bis@s1n.pw>
Date: Mon, 10 Aug 2020 23:44:20 +0200
Subject: clean this up when home

---
 docs/commands.md         |  31 +++++
 docs/configuration.md    | 342 +++++++++++++++++++++++++++++++++++++++++++++++
 docs/faq.md              |  21 +++
 docs/plugins.md          |  47 +++++++
 docs/setup.md            |  50 +++++++
 docs/starting-the-bot.md |  16 +++
 6 files changed, 507 insertions(+)
 create mode 100644 docs/commands.md
 create mode 100644 docs/configuration.md
 create mode 100644 docs/faq.md
 create mode 100644 docs/plugins.md
 create mode 100644 docs/setup.md
 create mode 100644 docs/starting-the-bot.md

(limited to 'docs')

diff --git a/docs/commands.md b/docs/commands.md
new file mode 100644
index 0000000..397cf16
--- /dev/null
+++ b/docs/commands.md
@@ -0,0 +1,31 @@
+# 🤖 Commands
+
+## Anywhere on the inbox server
+`!logs <user> <page>` Lists previous modmail logs with the specified user. If there are a lot of logs, they will be paginated. In this case, you can specify the page number to view as the second argument.  
+`!block <user> <time>` Blocks the specified user from using modmail. If a time is specified, the block is temporary.  
+`!unblock <user> <time>` Unblocks the specified user from using modmail. If a time is specified, the user will be scheduled to be unblocked after that time.  
+`!is_blocked <user>` Checks whether the user is blocked and for how long  
+`!s <shortcut> <text>` Adds a snippet (a canned response). Supports {1}, {2}, etc. for arguments. See below for how to use it.  
+`!edit_snippet <shortcut> <text>` Edits an existing snippet (alias `!es`)  
+`!delete_snippet <shortcut>` Deletes the specified snippet (alias `!ds`)  
+`!snippets` Lists all available snippets  
+`!version` Print the version of the bot you're running  
+`!newthread <user>` Opens a new thread with the specified user  
+
+## Inside a modmail thread
+`!reply <text>` Sends a reply to the user in the format "(Role) User: text" (alias `!r`)  
+`!anonreply <text>` Sends an anonymous reply to the user in the format "Role: text" (alias `!ar`)  
+`!close <time>` Closes the modmail thread. If a time is specified, the thread is scheduled to be closed later. Scheduled closing is cancelled if a message is sent to or received from the user.  
+`!logs <page>` Lists previous modmail logs with this user. If there are a lot of logs, they will be paginated. In this case, you can specify the page number to view as an argument.  
+`!block <time>` Blocks the user from using modmail. If a time is specified, the block is temporary.  
+`!unblock <time>` Unblocks the user from using modmail. If a time is specified, the user will be scheduled to be unblocked after that time.  
+`!!shortcut` Reply with a snippet. Replace `shortcut` with the snippet's actual shortcut.  
+`!!!shortcut` Reply with a snippet anonymously. Replace `shortcut` with the snippet's actual shortcut.  
+`!move <category>` If `allowMove` is enabled, moves the thread channel to the specified category  
+`!loglink` Shows the link to the current thread's log  
+`!suspend` Suspend a thread. The thread will act as closed and not receive any messages until unsuspended.  
+`!unsuspend` Unsuspend a thread  
+`!id` Prints the user's ID  
+`!alert` Pings you when the thread gets a new reply. Use `!alert cancel` to cancel.  
+
+To automatically reply without using !reply or !r, [enable `alwaysReply` in the config](configuration.md).
diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 0000000..cb4f2bb
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,342 @@
+# 📝 Configuration
+Haven't set up the bot yet? Check out [Setting up the bot](setup.md) first!
+
+## Table of contents
+- [Configuration file](#configuration-file) (start here)
+- [Adding new options](#adding-new-options)
+- [Required options](#required-options)
+- [Other options](#other-options)
+- [config.ini vs config.json](#configini-vs-configjson)
+- [Other formats](#other-formats)
+- [Environment variables](#environment-variables)
+
+## Configuration file
+All bot options are saved in a configuration file in the bot's folder.
+This is created during the [setup](setup.md) and is generally either `config.ini` or, if you've been using the bot for
+longer, `config.json`.
+
+The instructions on this page are for `config.ini` but can be adapted to `config.json` as well.
+See [config.ini vs config.json](#configini-vs-configjson) for more details.
+Note that the format of `.ini` and `.json` are different -- you can't simply rename a `.json` to `.ini` or
+vice versa.
+
+## Adding new options
+To add a new option to your `config.ini`, open the file in a text editor such as notepad.
+Each option is put on a new line, and follows the format `option = value`. For example, `mainGuildId = 1234`.
+
+**You need to restart the bot for configuration changes to take effect!**
+
+You can add comments in the config file by prefixing the line with `#`. Example:
+```ini
+# This is a comment
+option = value
+```
+
+### Toggle options
+Some options like `allowMove` are "**Toggle options**": they control whether certain features are enabled (on) or not (off).
+* To enable a toggle option, set its value to `on`, `true`, or `1`
+* To disable a toggle option, set its value to `off`, `false`, or `0`
+* E.g. `allowMove = on` or `allowMove = off`
+
+### "Accepts multiple values"
+Some options are marked as "**Accepts multiple values**". To give these options multiple values,
+write the option as `option[] = value` and repeat for every value. For example:
+
+```ini
+inboxServerPermission[] = kickMembers
+inboxServerPermission[] = manageMessages
+```
+
+You can also give these options a single value in the usual way, i.e. `inboxServerPermission = kickMembers`
+
+### Multiple lines of text
+For some options, such as `greetingMessage`, you might want to add text that spans multiple lines.
+To do that, use the same format as with "Accepts multiple values" above:
+
+```ini
+greetingMessage[] = Welcome to the server!
+greetingMessage[] = This is the second line of the greeting.
+greetingMessage[] = 
+greetingMessage[] = Fourth line! With an empty line in the middle.
+```
+
+## Required options
+
+#### token
+The bot user's token from [Discord Developer Portal](https://discordapp.com/developers/).
+
+#### mainGuildId
+Your server's ID, wrapped in quotes.
+
+#### mailGuildId
+For a two-server setup, the inbox server's ID.  
+For a single-server setup, same as [mainGuildId](#mainguildid).
+
+#### logChannelId
+ID of a channel on the inbox server where logs are posted after a modmail thread is closed
+
+## Other options
+
+#### accountAgeDeniedMessage
+**Default:** `Your Discord account is not old enough to contact modmail.`  
+See `requiredAccountAge` below
+
+#### allowMove
+**Default:** `off`  
+If enabled, allows you to move threads between categories using `!move <category>`
+
+#### allowUserClose
+**Default:** `off`  
+If enabled, users can use the close command to close threads by themselves from their DMs with the bot
+
+#### alwaysReply
+**Default:** `off`  
+If enabled, all messages in modmail threads will be sent to the user without having to use `!r`.  
+To send internal messages in the thread when this option is enabled, prefix them with `!note` (using your `prefix`),
+e.g. `!note This is an internal message`.
+
+#### alwaysReplyAnon
+**Default:** `off`  
+If `alwaysReply` is enabled, this option controls whether the auto-reply is anonymous
+
+#### attachmentStorage
+**Default:** `local`  
+Controls how attachments in modmail threads are stored. Possible values:
+* **local** - Files are saved locally on the machine running the bot
+* **discord** - Files are saved as attachments on a special channel on the inbox server. Requires `attachmentStorageChannelId` to be set.
+
+#### attachmentStorageChannelId
+**Default:** *None*  
+When using attachmentStorage is set to "discord", the id of the channel on the inbox server where attachments are saved
+
+#### botMentionResponse
+**Default:** *None*  
+If set, the bot auto-replies to bot mentions (pings) with this message. Use `{userMention}` in the text to ping the user back.
+
+#### categoryAutomation.newThread
+**Default:** *None*  
+ID of the category where new threads are opened. Also functions as a fallback for `categoryAutomation.newThreadFromGuild`.
+
+#### categoryAutomation.newThreadFromGuild.GUILDID
+**Default:** *None*  
+When running the bot on multiple main servers, this allows you to specify new thread categories for users from each guild. Example:
+```ini
+# When the user is from the server ID 94882524378968064, their modmail thread will be placed in the category ID 360863035130249235
+categoryAutomation.newThreadFromGuild.94882524378968064 = 360863035130249235
+# When the user is from the server ID 541484311354933258, their modmail thread will be placed in the category ID 542780020972716042
+categoryAutomation.newThreadFromGuild.541484311354933258 = 542780020972716042
+```
+
+#### closeMessage
+**Default:** *None*  
+If set, the bot sends this message to the user when the modmail thread is closed.
+
+#### commandAliases
+**Default:** *None*  
+Custom aliases/shortcuts for commands. Example:
+```ini
+# !mv is an alias/shortcut for !move
+commandAliases.mv = move
+# !x is an alias/shortcut for !close
+commandAliases.x = close
+```
+
+#### enableGreeting
+**Default:** `off`  
+When enabled, the bot will send a greeting DM to users that join the main server.
+
+#### greetingAttachment
+**Default:** *None*  
+Path to an image or other attachment to send as a greeting. Requires `enableGreeting` to be enabled.
+
+#### greetingMessage
+**Default:** *None*  
+Message to send as a greeting. Requires `enableGreeting` to be enabled. Example:
+```ini
+greetingMessage[] = Welcome to the server!
+greetingMessage[] = Remember to read the rules.
+```
+
+#### guildGreetings
+**Default:** *None*  
+When running the bot on multiple main servers, this allows you to set different greetings for each server. Example:
+```ini
+guildGreetings.94882524378968064.message = Welcome to server ID 94882524378968064!
+guildGreetings.94882524378968064.attachment = greeting.png
+
+guildGreetings.541484311354933258.message[] = Welcome to server ID 541484311354933258!
+guildGreetings.541484311354933258.message[] = Second line of the greeting.
+```
+
+#### ignoreAccidentalThreads
+**Default:** `off`  
+If enabled, the bot attempts to ignore common "accidental" messages that would start a new thread, such as "ok", "thanks", etc.
+
+#### inboxServerPermission
+**Default:** *None*  
+**Accepts multiple values.** Permission name, user id, or role id required to use bot commands on the inbox server.
+See ["Permissions" on this page](https://abal.moe/Eris/docs/reference) for supported permission names (e.g. `kickMembers`).
+
+#### timeOnServerDeniedMessage
+**Default:** `You haven't been a member of the server for long enough to contact modmail.`  
+If `requiredTimeOnServer` is set, users that are too new will be sent this message if they try to message modmail.
+
+#### mentionRole
+**Default:** `here`  
+**Accepts multiple values.** Role that is mentioned when new threads are created or the bot is mentioned.
+Accepted values are "here", "everyone", or a role id.
+Requires `pingOnBotMention` to be enabled.
+Set to an empty value (`mentionRole=`) to disable these pings entirely.
+
+#### mentionUserInThreadHeader
+**Default:** `off`  
+If enabled, mentions the user messaging modmail in the modmail thread's header.
+
+#### newThreadCategoryId
+**Default:** *None*  
+**Deprecated.** Same as `categoryAutomation.newThread`.
+
+#### pingOnBotMention
+**Default:** `on`  
+If enabled, the bot will mention staff (see `mentionRole` option) on the inbox server when the bot is mentioned on the main server.
+
+#### plugins
+**Default:** *None*  
+**Accepts multiple values.** External plugins to load on startup. See [Plugins](plugins.md) for more information.
+
+#### port
+**Default:** `8890`  
+Port to use for attachments (when `attachmentStorage` is set to `local`) and logs.  
+Make sure to do the necessary [port forwarding](https://portforward.com/) and add any needed firewall exceptions so the port is accessible from the internet.
+
+#### prefix
+**Default:** `!`  
+Prefix for bot commands
+
+#### relaySmallAttachmentsAsAttachments
+**Default:** `off`  
+If enabled, small attachments from users are sent as real attachments rather than links in modmail threads.
+The limit for "small" is 2MB by default; you can change this with the `smallAttachmentLimit` option.
+
+#### requiredAccountAge
+**Default:** *None*  
+Required account age for contacting modmail (in hours). If the account is not old enough, a new thread will not be created and the bot will reply with `accountAgeDeniedMessage` (if set) instead.
+
+#### requiredTimeOnServer
+**Default:** *None*  
+Required amount of time (in minutes) the user must be a member of the server before being able to contact modmail. If the user hasn't been a member of the server for the specified time, a new thread will not be created and the bot will reply with `timeOnServerDeniedMessage` (if set) instead.
+
+#### responseMessage
+**Default:** `Thank you for your message! Our mod team will reply to you here as soon as possible.`  
+The bot's response to the user when they message the bot and open a new modmail thread
+
+#### rolesInThreadHeader
+**Default:** `off`  
+If enabled, the user's roles will be shown in the modmail thread header
+
+#### smallAttachmentLimit
+**Default:** `2097152`  
+Size limit of `relaySmallAttachmentsAsAttachments` in bytes (default is 2MB)
+
+#### snippetPrefix
+**Default:** `!!`  
+Prefix for snippets
+
+#### snippetPrefixAnon
+**Default:** `!!!`  
+Prefix to use snippets anonymously
+
+#### status
+**Default:** `Message me for help`  
+The bot's "Playing" text
+
+#### syncPermissionsOnMove
+**Default:** `on`  
+If enabled, channel permissions for the thread are synchronized with the category when using `!move`. Requires `allowMove` to be enabled.
+
+#### threadTimestamps
+**Default:** `off`  
+If enabled, modmail threads will show accurate UTC timestamps for each message, in addition to Discord's own timestamps.
+Logs show these always, regardless of this setting.
+
+#### typingProxy
+**Default:** `off`  
+If enabled, any time a user is typing to modmail in their DMs, the modmail thread will show the bot as "typing"
+
+#### typingProxyReverse
+**Default:** `off`  
+If enabled, any time a moderator is typing in a modmail thread, the user will see the bot "typing" in their DMs
+
+#### updateNotifications
+**Default:** `on`  
+If enabled, the bot will automatically check for new bot updates periodically and notify about them at the top of new modmail threads
+
+#### url
+**Default:** *None*  
+URL to use for attachment and log links. Defaults to `http://IP:PORT`.
+
+#### useNicknames
+**Default:** `off`  
+If enabled, mod replies will use their nicknames (on the inbox server) instead of their usernames
+
+## config.ini vs config.json
+Earlier versions of the bot instructed you to create a `config.json` instead of a `config.ini`.
+**This is still fully supported, and will be in the future as well.**
+However, there are some differences between `config.ini` and `config.json`.
+
+### Formatting
+*See [the example on the Wikipedia page for JSON](https://en.wikipedia.org/wiki/JSON#Example)
+for a general overview of the JSON format.*
+
+* In `config.json`, all text values and IDs need to be wrapped in quotes, e.g. `"mainGuildId": "94882524378968064"`
+* In `config.json`, all numbers (other than IDs) are written without quotes, e.g. `"port": 3000`
+
+### Toggle options
+In `config.json`, valid values for toggle options are `true` and `false` (not quoted),
+which correspond to `on` and `off` in `config.ini`.
+
+### "Accepts multiple values"
+Multiple values are specified in `config.json` using arrays:
+```json
+{
+  "inboxPermission": [
+    "kickMembers",
+    "manageMessages"
+  ]
+}
+```
+
+### Multiple lines of text
+Since `config.json` is parsed using [JSON5](https://json5.org/), multiple lines of text are supported
+by escaping the newline with a backslash (`\ `):
+```json5
+{
+  "greetingMessage": "Welcome to the server!\
+This is the second line of the greeting."
+}
+```
+
+## Other formats
+Loading config values programmatically is also supported.
+Create a `config.js` in the bot's folder and export the config object with `module.exports`.
+All other configuration files take precedence, so make sure you don't have both.
+
+## Environment variables
+Config options can be passed via environment variables.
+
+To get the name of the corresponding environment variable for an option, convert the option to SNAKE_CASE with periods
+being replaced by two underscores and add `MM_` as a prefix. If adding multiple values for the same option, separate the
+values with two pipe characters: `||`.
+
+Examples:
+* `mainGuildId` -> `MM_MAIN_GUILD_ID`
+* `commandAliases.mv` -> `MM_COMMAND_ALIASES__MV`
+* From:  
+  ```ini
+  inboxServerPermission[] = kickMembers
+  inboxServerPermission[] = manageMessages
+  ```  
+  To:  
+  `MM_INBOX_SERVER_PERMISSION=kickMembers||manageMessages`
+
+The `port` option also accepts the environment variable `PORT` without a prefix, but `MM_PORT` takes precedence.
diff --git a/docs/faq.md b/docs/faq.md
new file mode 100644
index 0000000..29b0370
--- /dev/null
+++ b/docs/faq.md
@@ -0,0 +1,21 @@
+# 🙋 Frequently Asked Questions
+
+## In a [single-server setup](setup.md#single-server-setup), how do I hide modmails from regular users?
+1. Create a private category for modmail threads that only your server staff and the bot can see and set the option
+`categoryAutomation.newThread = 1234` (replace `1234` with the ID of the category)
+2. Set the `inboxServerPermission` option to limit who can use bot commands.
+   [Click here for more information.](configuration.md#inboxserverpermission)
+
+## My logs and/or attachments aren't loading!
+Since logs and attachments are both stored and sent directly from the machine running the bot, you'll need to make sure
+that the machine doesn't have a firewall blocking the bot and has the appropriate port forwardings set up.
+[You can find more information and instructions for port forwarding here.](https://portforward.com/) 
+By default, the bot uses the port **8890**.
+
+## I don't want attachments saved on my computer
+As an alternative to storing modmail attachments on the machine running the bot, they can be stored in a special Discord
+channel instead. Create a new text channel and then set the options `attachmentStorage = discord` and
+`attachmentStorageChannelId = 1234` (replace `1234` with the ID of the new channel).
+
+## I want to categorize my modmail threads in multiple categories
+Set `allowMove = on` to allow your staff to move threads to other categories with `!move`
diff --git a/docs/plugins.md b/docs/plugins.md
new file mode 100644
index 0000000..2a08558
--- /dev/null
+++ b/docs/plugins.md
@@ -0,0 +1,47 @@
+# 🧩 Plugins
+The bot supports loading external plugins.
+
+## Specifying plugins to load
+For each plugin file you'd like to load, add the file path to the [`plugins` option](configuration.md#plugins).
+The path is relative to the bot's folder.
+Plugins are automatically loaded on bot startup.
+
+## Creating a plugin
+Create a `.js` file that exports a function.
+This function will be called when the plugin is loaded, with 1 argument: an object that has the following properties:
+* `bot` - the [Eris Client object](https://abal.moe/Eris/docs/Client)
+* `knex` - the [Knex database object](https://knexjs.org/#Builder)
+* `config` - the loaded config
+* `commands` - an object with functions to add and manage commands
+* `attachments` - an object with functions to save attachments and manage attachment storage types
+
+See [src/plugins.js#L4](../src/plugins.js#L4) for more details
+
+### Example plugin file
+This example adds a command `!mycommand` that replies with `"Reply from my custom plugin!"` when the command is used inside a modmail inbox thread channel.
+```js
+module.exports = function({ bot, knex, config, commands }) {
+  commands.addInboxThreadCommand('mycommand', [], (msg, args, thread) => {
+    thread.replyToUser(msg.author, 'Reply from my custom plugin!');
+  });
+}
+```
+
+(Note the use of [object destructuring](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment#Unpacking_fields_from_objects_passed_as_function_parameter) in the function parameters)
+
+### Example of a custom attachment storage type
+This example adds a custom type for the `attachmentStorage` option called `"original"` that simply returns the original attachment URL without rehosting it in any way.
+```js
+module.exports = function({ attachments }) {
+  attachments.addStorageType('original', attachment => {
+    return { url: attachment.url };
+  });
+};
+```
+To use this custom attachment storage type, you would set the `attachmentStorage` config option to `"original"`.
+
+## Work in progress
+The current plugin API is fairly rudimentary and will be expanded on in the future.
+The API can change in non-major releases during this early stage. Keep an eye on [CHANGELOG.md](../CHANGELOG.md) for any changes.
+
+Please send any feature suggestions to the [issue tracker](https://github.com/Dragory/modmailbot/issues)!
diff --git a/docs/setup.md b/docs/setup.md
new file mode 100644
index 0000000..ab724f0
--- /dev/null
+++ b/docs/setup.md
@@ -0,0 +1,50 @@
+# 🛠️ Setting up the bot
+**Note:** This bot is run on your own machine or a server.  
+To keep it online, you need to keep the bot process running.
+
+## Terminology
+* **Main server** (or main guild) is the server where users will be contacting modmail from
+* **Inbox server** (or inbox guild, or mail guild) is the server where modmail threads will be created.
+  In a "single-server setup" this is the same server as the main server.
+* A **modmail thread** is a channel on the **inbox server** that contains the current exchange with the **user**.
+  These threads can be closed to archive them. One **user** can only have 1 modmail thread open at once.
+* A **moderator**, in modmail's context, is a server staff member who responds to and manages modmail threads
+* A **user**, in modmail's context, is a Discord user who is contacting modmail by DMing the bot
+
+## Prerequisites
+1. Create a bot account through the [Discord Developer Portal](https://discordapp.com/developers/)
+2. Invite the created bot to your server
+3. Install Node.js 10, 11, or 12
+    - Node.js 13 is currently not supported
+4. Download the latest bot version from [the releases page](https://github.com/Dragory/modmailbot/releases) and extract it to a folder
+5. In the bot's folder, make a copy of the file `config.example.ini` and rename the copy to `config.ini`
+
+## Single-server setup
+In this setup, modmail threads are opened on the main server in a special category.
+This is the recommended setup for small and medium sized servers.
+
+1. Open `config.ini` in a text editor and fill in the required values. `mainGuildId` and `mailGuildId` should both be set to your server's id.
+2. On a new line at the end of `config.ini`, add `categoryAutomation.newThread = CATEGORY_ID_HERE`
+    - Replace `CATEGORY_ID_HERE` with the ID of the category where new modmail threads should go
+3. Make sure the bot has `Manage Channels`, `Manage Messages`, and `Attach Files` permissions in the category
+4. **[🏃 Start the bot!](starting-the-bot.md)**
+5. Want to change other bot options? See **[📝 Configuration](configuration.md)**
+6. Have any other questions? Check out the **[🙋 Frequently Asked Questions](faq.md)** or
+   **[join the support server!](../README.md#support-server)**
+
+## Two-server setup
+In this setup, modmail threads are opened on a separate inbox server.
+This is the recommended setup for large servers that get a lot of modmails, where a single-server setup could get messy.
+You might also want this setup for privacy concerns*.
+
+1. Create an inbox server on Discord
+2. Invite the bot to the inbox server.
+3. Open `config.ini` in a text editor and fill in the values
+4. Make sure the bot has the `Manage Channels`, `Manage Messages`, and `Attach Files` permissions on the **inbox** server
+5. **[🏃 Start the bot!](starting-the-bot.md)**
+5. Want to change other bot options? See **[📝 Configuration](configuration.md)**
+6. Have any other questions? Check out the **[🙋 Frequently Asked Questions](faq.md)** or
+   **[join the support server!](../README.md#support-server)**
+
+*\* Since all channel names, even for channels you can't see, are public information through the API, a user with a
+modified client could see the names of all users contacting modmail through the modmail channel names.* 
diff --git a/docs/starting-the-bot.md b/docs/starting-the-bot.md
new file mode 100644
index 0000000..624c8f2
--- /dev/null
+++ b/docs/starting-the-bot.md
@@ -0,0 +1,16 @@
+# 🏃 Starting the bot
+Haven't set up the bot yet? Check out [Setting up the bot](setup.md) first!
+
+## Windows
+* To start the bot, double-click on `start.bat` in the bot's folder
+* To shut down the bot, close the console window
+* To restart the bot, close the console window and then double-click on `start.bat` again
+
+## Linux / macOS / Advanced on Windows
+The following assumes basic knowledge about using command line tools.
+1. Before first start-up and after every update, run `npm ci` in the bot's folder
+2. Run `npm start` in the bot's folder to start the bot
+
+## Process managers
+If you're using a process manager like PM2, the command to run is `npm start`.
+A PM2 process file, `modmailbot-pm2.json`, is included in the repository.
-- 
cgit v1.2.3