Official repository for Clinet, a Discord bot intended for assistance and control within your guilds.
Clone or download
JoshuaDoes Add query services in voice services fashion with support for command…
…-like environments, migrate Wolfram|Alpha, DuckDuckGo, and custom response query functions to query service interfaces, move swear filter check to after command and query checks, move queryImgur function into cmd-imgur.go, replace repetitive map initializers with initializer functions, remove guildData initializers throughout messages.go, clean up command prefix checkers to remove repetitive code, and prevent typingEvent from executing if updatedMessageEvent is true
Latest commit 38bf4aa Jan 7, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
keypair Fix screenshot command, add screenshot NLP command, remove Thum.IO AP… Dec 21, 2018
.gitignore Begin phasing out debugLog in favor of log stdlib Nov 25, 2018
CNAME Create CNAME Aug 29, 2018
LICENSE Add DuckDuckGo Instant Answer API support, try DGG before Wolfram Feb 6, 2018
README.md Update the Discord server invite link Dec 3, 2018
_config.yml Set theme jekyll-theme-hacker Aug 29, 2018
botinfo.go Update repo name references, remove .update leftover Aug 29, 2018
cmd-clinet.go Prevent permission checks if no permissions are required, debug only … Nov 9, 2018
cmd-cve.go Split related commands into their own files Aug 2, 2018
cmd-debug.go Add debug toggle command, add additional details to botinfo command, … Sep 20, 2018
cmd-geoip.go Add starboard, add more logging events, add logging management, add g… Aug 29, 2018
cmd-github.go Add support for GitHub trending Nov 26, 2018
cmd-image.go Add ability to use last image in chat history for image command, remo… Oct 25, 2018
cmd-imgur.go Add query services in voice services fashion with support for command… Jan 7, 2019
cmd-info.go Add socials setting to user settings and add socials display to userinfo Nov 24, 2018
cmd-minecraft.go Add ability to fetch new username from old username and view username… Oct 19, 2018
cmd-moderation.go Fix user parsing in kick and ban commands and prevent kicking or bann… Oct 14, 2018
cmd-nlp.go Add starboard, add more logging events, add logging management, add g… Aug 29, 2018
cmd-random.go Re-add timeout to screenshot command, add automatic URL parsing to sc… Dec 21, 2018
cmd-remind.go Add list and hacky delete methods to remind command Oct 28, 2018
cmd-roleme.go Add ability to list roleme events by not specifying any arguments and… Nov 2, 2018
cmd-settings.go Add query services in voice services fashion with support for command… Jan 7, 2019
cmd-starboard.go Fix screenshot command, add screenshot NLP command, remove Thum.IO AP… Dec 21, 2018
cmd-urbandictionary.go Allow multi-word terms with Urban Dictionary Aug 2, 2018
cmd-voice.go Add lyrics command and update README.md Nov 18, 2018
cmd-xkcd.go Various fixes/changes (#6) Sep 12, 2018
commands.go Re-add timeout to screenshot command, add automatic URL parsing to sc… Dec 21, 2018
config.example.json Attempt query with new conversation if past conversation failed to ge… Nov 8, 2018
config.go Add query services in voice services fashion with support for command… Jan 7, 2019
embed.go Add ability to use last image in chat history for image command, remo… Oct 25, 2018
events.go Prevent permission checks if no permissions are required, debug only … Nov 9, 2018
go.mod Add lyrics command and update README.md Nov 18, 2018
go.sum Add lyrics command and update README.md Nov 18, 2018
initializers.go Add query services in voice services fashion with support for command… Jan 7, 2019
logging.go Migrate main.go to log interface and add debug flag Nov 25, 2018
main.go Add query services in voice services fashion with support for command… Jan 7, 2019
messages.go Add query services in voice services fashion with support for command… Jan 7, 2019
nlp.go Fix screenshot command, add screenshot NLP command, remove Thum.IO AP… Dec 21, 2018
others.go Prevent permission checks if no permissions are required, debug only … Nov 9, 2018
pages.go Fix issues with pagination framework where page count was incorrect a… Oct 19, 2018
process.go Fix signal interrupt handling for Linux, unsure about effects under o… Nov 25, 2018
queryhandler-customresponse.go Add query services in voice services fashion with support for command… Jan 7, 2019
queryhandler-duckduck.go Add query services in voice services fashion with support for command… Jan 7, 2019
queryhandler-wolfram.go Add query services in voice services fashion with support for command… Jan 7, 2019
queryhandlers.go Add query services in voice services fashion with support for command… Jan 7, 2019
recovery.go Separate process handlers and panic recovery handlers into separate f… Nov 25, 2018
swearfilter.go Fix misspell issues Sep 11, 2018
voice.go Quality of life improvement by disabling automatic now playing embeds… Nov 18, 2018
voicehandler-bandcamp.go Add support for hourly tip messages (disabled by default) and rename … Oct 29, 2018
voicehandler-direct.go Remove error reporting from TestURL in Direct voice handler services Oct 31, 2018
voicehandler-soundcloud.go Add BandCamp voice service handler Oct 28, 2018
voicehandler-spotify.go Add BandCamp voice service handler Oct 28, 2018
voicehandler-youtube.go Add BandCamp voice service handler Oct 28, 2018
voicehandlers.go Add query services in voice services fashion with support for command… Jan 7, 2019

README.md

clinet

A Discord bot intended for assistance and control within your guilds

Go Report Card

Discord Bots


Using the official up-to-date version of Clinet

  1. Click on this link to invite Clinet into your Discord server.
    1. The Administrator permission is not required. The invite link above only requests the permission to handle all of Clinet's advanced features, saving time from going through and adding missing permissions. Should you still wish to manage these permissions yourself, do not grant the bot the Administrator permission. At a later date, the bot will give errors for permissions it does not have when asked to do something, and should sending the error message fail it will warn the server owner in a DM.
  2. (Optional) Join the official Clinet Discord server to get updates on the latest features and changes Clinet has to offer, get help with issues you may be having, and even use bot testing channels to test-drive the bot before deciding if it's right for your community!
  3. Enjoy!

What does it do?

After the Clinet bot is invited to your Discord server, it will immediately begin listening for certain keywords within conversations to trigger certain events.

Clinet will listen for a message that tags it and contains a question mark (?) suffix to detect when it is being queried with a question. It begins by checking a list of RegEx expressions stored in the bot configuration to look for configurable responses that bot hosters can set for their specific instance of the bot. If nothing is found, it then continues on to query DuckDuckGo's Instant Answers API for a possible response. If DuckDuckGo comes up short, it finally queries Wolfram|Alpha as a last resort (as Wolfram|Alpha's API services are limited for non-paying developers). Should no responses be found from any of the three sources, Clinet tells the user that there was an error finding the response.

Additionally, Clinet supports various functionalities not available in question-response queries using commands. Commands are prefixed by default using cli$ and sometimes take parameters to control the output and action of the command.

Finally, Clinet has some very useful message management features proven to be successful in the servers it resides in. If you send a query and make a mistake, for example if you misspell a word, forget to tag the bot, or forget a question mark, you don't have to send a whole new message - just edit the previous message with the fix and Clinet happily responds to the updated message. Adding onto this, you can even edit a message that had a successful response - Clinet will happily edit its response message with the new response to the updated query. Lastly, if you delete your original query message, Clinet will help with the chat cleanup and delete its response message. These message management features work for both question queries and commands, and soon will be interwoven into music playback commands.

Commands

The default configuration of Clinet uses cli$ as the command prefix. This can be configured in the bot configuration for bot hosts, however remains a unique command prefix that should never interfere with another bot's default command prefix.

All of Clinet's commands respond using a rich embed with all fields inlined to save chat screen estate on desktop and web versions of Discord while maintaining a clean output everywhere.

For a list of available commands, use the cli$help command in a server with Clinet.


Rolling your own locally

In order to run Clinet locally, you must have already installed a working Golang environment on your development system. Clinet is currently built using Golang 1.11, and other versions of Go are not guaranteed to be supported at this time.

Fetching Clinet and dependencies

Run go get github.com/JoshuaDoes/clinet and watch the magic happen!

Building

Clinet is built using a compiler wrapper known as govvv, and opts to use an altered version to support additional things. govvv acts as a git status injector for the output compiled binary, taking current statuses of the git repo Clinet is in and injecting them into uninitialized strings in the main source file to be used in the command cli$version. Simply follow the instructions on the govvv repo page to learn how to install and use it, then run govvv build in the Clinet repo directory.

Acquiring necessary API keys

Clinet's functionality relies on a set of different API keys and access tokens, and without them sports less features to interact with and use. The official bot has all of these already, but if you're looking to roll your own instance of the bot you'll need to acquire these on your own (an exercise left up to you).

Services Requirements
Wolfram|Alpha App ID
DuckDuckGo App name (can be anything)
YouTube Search API key
Imgur Client ID
SoundCloud Client ID and app version

Writing the configuration

Clinet stores its configuration in a file named config.json using the JSON data structure. It has a number of configurable variables and will always globally override a server's settings if it disables a feature. Passing the command line argument -config test.json will instead load the bot configuration from test.json.

The following is an example configuration file:

{
	"botToken": "[insert bot token here]",
	"botName": "Clinet",
	"botOwnerID": "[insert bot owner's user ID here]",
	"cmdPrefix": "cli$",
	"sendOwnerStackTraces": true,
	"botKeys": {
		"wolframAppID": "[insert Wolfram|Alpha app ID here]",
		"ddgAppName": "Clinet",
		"youtubeAPIKey": "[insert YouTube API key here]",
		"imgurClientID": "[insert Imgur client ID here]",
		"soundcloudClientID": "[insert SoundCloud client ID here]",
		"soundcloudAppVersion": "[insert SoundCloud app version here]"
	},
	"botOptions": {
		"maxPingCount": 4,
		"sendTypingEvent": true,
		"useCustomResponses": true,
		"useDuckDuckGo": true,
		"useGitHub": true,
		"useImgur": true,
		"useSoundCloud": true,
		"useWolframAlpha": true,
		"useXKCD": true,
		"useYouTube": true,
		"wolframDeniedPods": [
			"Locations",
			"Nearby locations",
			"Local map",
			"Inferred local map",
			"Inferred nearest city center",
			"IP address",
			"IP address registrant",
			"Clocks"
		],
		"youtubeMaxResults": 5
	},
	"debugMode": false,
	"customResponses": [
		{
			"expression": "(.*)(?i)raining(.*)tacos(.*)",
			"cmdResponses": [
				{
					"commandName": "play",
					"args": [
						"https://youtube.com/watch?v=npjF032TDDQ"
					]
				}
			]
		},
		{
			"expression": "(.*)(?i)who(.*)JoshuaDoes(.*)",
			"responses": [
				{
					"responseEmbed": {
						"title": "Who is JoshuaDoes?",
						"description": "JoshuaDoes is a human being.",
						"color": 1842204
					}
				}
			]
		}
	],
	"customStatuses": [
		{
			"type": 0,
			"status": "`cli$help`!"
		},
		{
			"type": 0,
			"status": "experimentally!"
		},
		{
			"type": 0,
			"status": "in the Go Playground!"
		},
		{
			"type": 0,
			"status": "a nearly finished me!"
		},
		{
			"type": 1,
			"status": "some tunes with users!"
		},
		{
			"type": 2,
			"status": "rewritten code!",
			"url": "https://github.com/JoshuaDoes/clinet-discord"
		}
	]
}

Most of the above configuration options should be self-explanatory, but here's some explanations for a few of the less guessable ones:

Variable Description
botToken The token of the bot account Clinet should log into. Can be acquired by creating an application and then declaring it as a bot user and/or selecting a pre-existing bot user application and acquiring the bot token under the APP BOT USER section.
botOwnerID The user ID of the bot owner. Can be acquired by enabling developer mode on Discord, right clicking your user in a server's user list, and clicking Copy ID. If Clinet crashes and recovers from the crash, the error and a full stack trace will be directly messaged to whatever user this option is set to.
sendOwnerStackTraces If this is set to true, the bot owner specified in botOwnerID will receive crash reports when Clinet recovers from a crash.
botOptions -> maxPingCount The amount of ping messages to send to Discord to test the ping average when using the ping command. This has a maximum of 5 to prevent inconsistent results due to Discord's API ratelimits, whereas the example configuration sets this to 4 so the results embed isn't stuck because of the API rate limit and can send immediately.
botOptions -> sendTypingEvent Whether or not to send a typing notification in a channel containing a query or command for Clinet to respond to. Helpful for queries or commands that take a little longer than usual to respond to so users know the bot isn't broken.
botOptions -> wolframDeniedPods An array of pod titles to skip over when creating a list of responses to use in a rich embed response from a Wolfram|Alpha query. The default list is highly recommended for bot hosters concerned with the privacy of the bot's host location.
botOptions -> youtubeMaxResults The total amount of results to display per page for YouTube searches via the cli$youtube search command. Maximum of 253.
debugMode Debug mode enables various console debugging features, such as chat output and other detailed information about what Clinet is up to.
customResponses Stored as objects in an array, custom responses are exactly what the name depicts. Each object contains an expression variable, which stores a valid regular expression, and a responses array, which itself contains objects randomly selected by the main program for different responseEmbed responses each time the custom response is queried. Alternatively, you can specify a cmdResponses array, which also contains objects randomly selected by the main program for different commandName commands to execute with the arguments in args. Command responses are direct executions of available commands in Clinet with any given parameters.
customStatuses Stored as objects in an array, custom statuses are used to set the bot's presence. Each object contains a type variable, which stores integers 0, 1, and 2, which are "Playing", "Listening to", and "Streaming" respectively, and a status variable, which stores the status text to use. If the type is set to 2, you can also set a url variable to use as the stream URL.

The configuration file by default will never be included in git commits, as declared by .gitignore. This is to prevent accidental leakage of API keys and bot tokens.

Running Clinet

Finally, to run Clinet, simply type ./clinet in your terminal/shell or .\clinet.exe in your command prompt. If everything goes well, you can find your bot user application and generate an OAuth2 URL to invite the bot into various servers in which you have the Administrator permission of.

Panic recovery

If Clinet ever crashes from a panic, custom-made panic recovery will save the crash message to crash.txt and the stack trace to stacktrace.txt in the bot's working directory. When Clinet is next started up, it will send the crash message and the file of the stack trace to the user specified in the configuration option botOwnerID and proceed to delete the two files.

Running Clinet by itself will spawn a "master" process with a few small jobs: Spawning a "bot" process, restarting the "bot" process if it exits for any reason, and closing the "bot" process if the "master" process ever exits for any reason. This is to ensure that, even if the "bot" process crashes, Clinet can continue running and instantly report the crash to the user specified in the configuration option botOwnerID.

States

If you close Clinet after running it long enough for it to merely exist on Discord, you'll notice a new folder called state. This folder contains "states" of various structs within Clinet's memory, stored in JSON format. Upon reopening Clinet, these state files are then loaded into memory so Clinet can (for the most part) return to its original "state" before it was closed. States were added as helpers to panic recovery so users can continue with what they were doing.

Updating

If you want to keep Clinet up to date without manually running go get github.com/JoshuaDoes/clinet, go build github.com/JoshuaDoes/clinet, and running Clinet again, you have the full ability to do so! Make sure your Discord user ID is specified as the bot owner in Clinet's configuration and run cli$update whenever a new commit is pushed. And if you need to make sure it works without waiting on a new update, run cli$update force.


Support

For help and support with Clinet, visit the Clinet Discord server and ask for an online developer.

License

The source code for Clinet is released under the MIT License. See LICENSE for more details.

Donations

All donations are highly appreciated. They help me pay for the server costs to keep Clinet running and even help point my attention span to Clinet to fix issues and implement newer and better features!

Donate