---

~ シンプル ~

A simple multi purpose discord bot written in Go (discord.go)
with focus on stability and reliability

     

Branch	Tests CI	Docker CD	Releases CD
master (stable)
dev (canary)

Invite

Here you can choose between the stable or canary version of shinpuru:

Intro

シンプル (shinpuru), a simple (as the name says), multi-purpose Discord Bot written in Go, using bwmarrin's package discord.go as API and gateway wrapper and ken as slash command and interaction framework. The focus on this bot is to provide general purpose, administration and security tools while keeping stability, reliability and maintainability in focus.

shinpuru is mainly used as administration and security tool on my development discord. Feel free to drop by to see shinpuru in action! 😉

Features

Slash Commands

shinpuru mainly uses slash commands to interact with the bot. In the wiki, you can find an automatically generated list of commands, their descriptions and how to use them (or here you can find a more interactive list in the web interface).

You can also find a searchable list in the web interface of shinpuru.

Web Interface

If you are sick of using commands, you can also use the web interface of shinpuru. Simply log in with your Discord Account (alternatively, you can also use the /login command).

Most features of shinpuru available via slash commands are also accessible in the web interface with additional visualization and information provided.

REST API

The web interface simply connects to the REST API exposed by the web server of shinpuru. You can also acquire an API token linked to your account to access the REST API directly, if you want.

Here you can read more about how to connect to shinpuru's REST API and which endpoints are available.

Chat Features

Code Execution

When someone posts code inside a code block, shinpuru can extract the code and language and execute it outputting the result into chat.

The code is picked up and sent to a code execution engine, which safely executes the code and sends back the result via a REST API. Therefore, you can chose between ranna or JDoodle in the config.

Karma

shinpuru features a Karma system which is inspired by Reddit. You can define specific emotes which, when attached to a message, increase or reduce the karma points of a member. You can also specify the amount of "tokens" which can be spent each hour as well as a penalty for giving negative karma, which also takes karma from the executor to prevent downvote spam.

It is also possible to execute actions when passing specific amounts of karma. For example, you can add or remove roles, send messages or even kick/ban members depending on their karma points.

Color Reactions

Another unique feature of shinpuru are color reactions. When enabled (see /colorreaction), shinpuru can fetch colors from chat messages and display them into a reaction. When clicked on the reaction, more information about the color is then posted into chat.

Votes

You can simply create votes using the /vote slash command where users can pseudo anonymously vote using reactions.

Twitch Notifications

You can add names of twitch streamers to a watchlist (see /twitchnotify) and when they go live, a notification message in sent into the specified channel.

Quote Messages

You can use the /quote command to quote messages by ID or link (even cross-channel).

Starboard

As literally any other bot, shinpuru also features a starboard! You can even specify an amount of karma members get when their message get into the starboard.

Channel Statistics

You can use the /channelstats command to analyze contribution statistics for specific text channels.

Guild Security & Moderation

Report System

shinpuru features a deeply integrated reporting and moderation system. You can create reports for members who violate guild rules which then are posted into a modlog channel (if specified). Also, all reports of a member can be viewed on their user profiles as well as in the web interface.

Of course, you can also kick and ban members with shinpuru, which also creates a report record in the modlog. It is even possible to create so called "ghost reports". It allows to report or ban members by ID which are no more part of the server.

When a member wants to request an unban, this can be done via the web interface when navigating to <webAddress>/unbanme.

Guild Backups

When enabled, shinpuru will create a backup of your guild's infrastructure every 12 hours. This includes guild settings, channels (names, positions and groups), roles (names, positions and permissions) and members (nicknames and applied roles).

When your guild gets raided or an admin goes rouge, you can simply choose one of the created backups and reset the guilds state.

The last 10 backups are stored and can be reviewed in the web interface.

Raid Alerting

This system allows you to set a threshold of new user ingress rate. When this rate exceeds, for example when a lot of (bot) accounts flush in to your guild (aka raiding), all admins of the guild will be alerted via DM. Also, the guilds moderation setting will be raised to Highest so that only users with roles or a valid phone number can chat.

Additionally, all joined users after the event triggered are logged in a list which can be viewed in the web interface. You can also use this list to bulk kick or ban users captured in the antiraid join list.

Docker

Read about how to host shinpuru using the provided Docker image in the wiki article.

Compiling

Read about self-compiling in the wiki article.

Public Packages

• github.com/zekroTJA/shinpuru/pkg/validators
  Package validators provides some (more or less) general purpose validator functions for user inputs.

• github.com/zekroTJA/shinpuru/pkg/checksum
  Package checksum provides functions to generate a hash sum from any given object.

• github.com/zekroTJA/shinpuru/pkg/stringutil
  Package stringutil provides generl string utility functions.

• github.com/zekroTJA/shinpuru/pkg/thumbnail
  Package thumbnail provides simple functionalities to generate thumbnails from images with a max witdh or height.

• github.com/zekroTJA/shinpuru/pkg/multierror
  Package multierror impements handling multiple errors as one error object.

• github.com/zekroTJA/shinpuru/pkg/jdoodle
  Package jdoodle provides an API wrapper for the jdoodle execute and credit-spent REST API.

• github.com/zekroTJA/shinpuru/pkg/lctimer
  Package lctimer provides a life cycle timer which calls registered callback handlers on timer elapse. This package is a huge buggy piece of crap, please don't use it. :)

• github.com/zekroTJA/shinpuru/pkg/rediscmdstore
  Package rediscmdstore provides an implementation of github.com/zekrotja/ken/store.CommandStore using a redis client to store the command cache.

• github.com/zekroTJA/shinpuru/pkg/etag
  Package etag implements generation functionalities for the ETag specification of RFC7273 2.3. https://tools.ietf.org/html/rfc7232#section-2.3.1

• github.com/zekroTJA/shinpuru/pkg/fetch
  Package fetch provides functionalities to fetch roles, channels, members and users by so called resolavbles. That means, these functions try to match a member, role or channel by their names, displaynames, IDs or mentions as greedy as prossible.

• github.com/zekroTJA/shinpuru/pkg/argp
  Package argp is a stupid simple flag (argument) parser which allows to parse flags without panicing when non-registered flags are passed.

• github.com/zekroTJA/shinpuru/pkg/inline
  Package inline provides general inline operation functions like inline if or null coalescence.

• github.com/zekroTJA/shinpuru/pkg/timerstack
  Package timerstack provides a timer which can execute multiple delayed functions one after one.

• github.com/zekroTJA/shinpuru/pkg/twitchnotify
  Package twitchnotify provides functionalities to watch the state of twitch streams and notifying changes by polling the twitch REST API.

• github.com/zekroTJA/shinpuru/pkg/boolutil
  Package boolutil provides simple utility functions around booleans.

• github.com/zekroTJA/shinpuru/pkg/bytecount
  Package bytecount provides functionalities to format byte counts.

• github.com/zekroTJA/shinpuru/pkg/timeutil
  Package timeutil provides some general purpose functionalities around the time package.

• github.com/zekroTJA/shinpuru/pkg/httpreq
  Package httpreq provides general utilities for around net/http requests for a simpler API and extra utilities for parsing JSON request and response boddies.

• github.com/zekroTJA/shinpuru/pkg/voidbuffer
  Package voidbuffer provides a simple, concurrency proof push buffer with a fixed size which "removes" firstly pushed values when fully filled.

• github.com/zekroTJA/shinpuru/pkg/lokiwriter
  Package lokiwriter implements rogu.Writer to push logs to a Grafana Loki instance.

• github.com/zekroTJA/shinpuru/pkg/roleutil
  Package roleutil provides general purpose utilities for discordgo.Role objects and arrays.

• github.com/zekroTJA/shinpuru/pkg/slices
  Package slices adds generic utility functionalities for slices.

• github.com/zekroTJA/shinpuru/pkg/logmsg
  No package description.

• github.com/zekroTJA/shinpuru/pkg/permissions
  Package permissions provides functionalities to calculate, update and merge arrays of permission domain rules. Read this to get more information about how permission domains and rules are working: https://github.com/zekroTJA/shinpuru/wiki/Permissions-Guide

• github.com/zekroTJA/shinpuru/pkg/hammertime
  Package hammertime provides functionailities to format a time.Time into a Discord timestamp mention. The name was used after the very useful web app hammertime.djdavid98.art.

• github.com/zekroTJA/shinpuru/pkg/discordutil
  Package discordutil provides general purpose extensuion functionalities for discordgo.

• github.com/zekroTJA/shinpuru/pkg/onetimeauth
  Package onetimeout provides short duration valid JWT tokens which are only valid exactly once.

• github.com/zekroTJA/shinpuru/pkg/limiter
  Package limiter provides a fiber middleware for a bucket based request rate limiter.

• github.com/zekroTJA/shinpuru/pkg/angularservice
  Package angularservice provides bindings to start an Angular development server via the Angular CLI.

• github.com/zekroTJA/shinpuru/pkg/regexputil
  Package regexutil provides additional utility functions used with regular expressions.

• github.com/zekroTJA/shinpuru/pkg/colors
  Package color provides general utilities for image/color objects and color codes.

• github.com/zekroTJA/shinpuru/pkg/random
  Package random provides some general purpose cryptographically pseudo-random utilities.

• github.com/zekroTJA/shinpuru/pkg/versioncheck
  Package versioncheck provides endpoints to retrieve version information via different providers and utilities to compare versions.

• github.com/zekroTJA/shinpuru/pkg/embedbuilder
  Package embedbuilder provides a builder pattern to create discordgo message embeds.

• github.com/zekroTJA/shinpuru/pkg/hashutil
  Package hashutil provides general utility functionalities to generate simple and fast hashes with salt and pepper.

• github.com/zekroTJA/shinpuru/pkg/ctypes
  Package ctype provides some custom types with useful function extensions.

• github.com/zekroTJA/shinpuru/pkg/msgcollector
  Package msgcollector provides functionalities to collect messages in a channel in conect of a single command request.

• github.com/zekroTJA/shinpuru/pkg/acceptmsg
  Package acceptmsg provides a message model for discordgo which can be accepted or declined via message reactions.

• github.com/zekroTJA/shinpuru/pkg/startuptime
  Package startuptime provides simple functionalities to measure the startup time of an application.

• github.com/zekroTJA/shinpuru/pkg/discordoauth
  package discordoauth provides fasthttp handlers to authenticate with via the Discord OAuth2 endpoint.

• github.com/zekroTJA/shinpuru/pkg/giphy
  Package giphy provides a crappy and inclomplete - but at least bloat free - Giphy API client.

• github.com/zekroTJA/shinpuru/pkg/mody
  Package mody allows to modify fields in an object.

• github.com/zekroTJA/shinpuru/pkg/intutil
  Package intutil provides some utility functionalities for integers.

• github.com/zekroTJA/shinpuru/pkg/mimefix
  +build windows

Third party dependencies

Back End

• bwmarrin/discordgo (v0.27.1)
• bwmarrin/snowflake (v0.3.0)
• esimov/stackblur-go (v1.1.0)
• gabriel-vasile/mimetype (v1.4.2)
• generaltso/vibrant (v0.0.0-20200703055536-90f922bee78c)
• go-ping/ping (v1.1.0)
• redis/v8 (v8.11.5)
• go-sql-driver/mysql (v1.7.1)
• fiber/v2 (v2.46.0)
• jwt/v4 (v4.5.0)
• joho/godotenv (v1.5.1)
• kataras/hcaptcha (v0.0.2)
• makeworld-the-better-one/go-isemoji (v1.3.0)
• manifoldco/promptui (v0.9.0)
• minio/minio-go (v6.0.14+incompatible)
• narqo/go-badge (v0.0.0-20221212191103-ba83bed45a1a)
• prometheus/client_golang (v1.15.1)
• qiangxue/fasthttp-routing (v0.0.0-20160225050629-6ccdc2a18d87)
• ranna-go/ranna (v0.3.0)
• cron/v3 (v3.0.1)
• rs/xid (v1.5.0)
• di/v2 (v2.4.2)
• stretchr/testify (v1.8.3)
• traefik/paerser (v0.2.0)
• valyala/fasthttp (v1.47.0)
• wcharczuk/go-chart (v2.0.1+incompatible)
• zekroTJA/colorname (v1.0.0)
• zekroTJA/ratelimit (v1.1.1)
• zekroTJA/timedmap (v1.5.1)
• zekrotja/dgrs (v0.5.7)
• zekrotja/jwt (v0.0.0-20220515133240-d66362c9fbc9)
• zekrotja/ken (v0.18.0)
• zekrotja/promtail (v0.0.0-20230303162843-4e609d577b74)
• zekrotja/rogu (v0.5.0)
• zekrotja/sop (v0.3.1)
• x/image (v0.7.0)
• x/sys (v0.8.0)
• x/time (v0.3.0)
• gopkg.in/yaml.v2 (v2.4.0)

Web Front End

• @hcaptcha/react-hcaptcha (^1.4.4)
• byte-formatter (^1.0.1)
• color (^4.2.1)
• date-fns (^2.28.0)
• debounce (^1.2.1)
• emoji.json (^14.0.0)
• fuse.js (^6.6.2)
• i18next (^22.4.14)
• i18next-browser-languagedetector (^7.0.1)
• i18next-http-backend (^2.2.0)
• react (^18.2.0)
• react-dom (^18.2.0)
• react-fast-marquee (^1.3.5)
• react-i18next (^12.2.0)
• react-markdown (^8.0.1)
• react-router (^6.0.2)
• react-router-dom (^6.2.1)
• react-scripts (5.0.0)
• react-spinners (^0.13.8)
• react-uid (^2.3.1)
• react-wavify (^1.7.0)
• sass (^1.49.0)
• styled-components (^5.3.0)
• web-vitals (^3.3.1)
• zustand (^4.3.7)

Assets

• Icons uded from Tabler Icons as well as from Hero Icons
• Discord Icon used from Discord's Branding Resources

The mascot artwork is created by the wonderful artist Kuglu. Please feel free to give them a visit. 💖

Copyright © 2018-present zekro Development (Ringo Hoffmann).
Covered by the MIT License.