karmabot

README

karmabot is a Slack bot that listens for and performs karma operations (aka upvotes/downvotes).

Syntax

• upvote a user: <user>++
• downvote a user: <user>--
• add/subtract multiple points at once:
  • <user>++ - 1 point
  • <user>+++ - 2 points
  • and so on, limited to maxpoints points (see the Usage section below)
• add a message/reason for a karma operation:
  • <user>++ for <message>; or
  • <user>++ <message>
• query a user's current points: <user>==
• upvote/downvote a user by adding reactjis to their message
• motivate.im support:
  • ?m <user>
  • !m <user>
• leaderboard:
  • <karma|karmabot> <leaderboard|top|highscores>
  • to list more than leaderboardlimit (see the Usage section below), you may append the number of users to list to the command above. e.g. karmabot top 20
• user aliases:
  • it is possible to alias different usernames to one main username by passing the aliases as a cli option to the karmabot binary. syntax: -alias main++alias1++alias2++...++aliasN
  • repeat the option for every alias that you want to configure
• karma throwback:
  • <karma|karmabot> throwback [user]
  • returns a random karma operation that happened to a specific user.

note: <user> does not have to be a Slack username. However, karmabot supports Slack autocompletion and so the following messages are parsed correctly:

• @username: ++
• @username++
• username ++
• !m @username:
• etc.

Installation

Use the Docker images

• kamaln7/karmabot:latest
• kamaln7/karmabot:latest-webui
• kamaln7/karmabotctl:latest

Download a Pre-built Release

1. head to the repo's releases page and download the appropriate latest release's binary for your system

Build from Source

1. clone the repo (find the latest version number in the releases page):
   1. git clone -b v1.5.2 https://github.com/kamaln7/karmabot.git
   2. cd karmabot
2. install dependencies
   1. run go mod download
3. run go build in /cmd/karmabot and /cmd/karmabotctl 2. cd cmd/karmabot 3. go build 4. cd ../karmabotctl 5. go build

Usage

1. add a Slack Bot integration: https://team.slack.com/apps/A0F7YS25R-bots. an avatar is available here.
2. invite karmabot to any existing channels and all future channels (this is a limitation of Slack's bot API, unfortunately)
3. run karmabot. the following options are supported. you can use environment variables as well, but any CLI options you pass will take precedence.

option	required?	description	default	env var
-token string	yes	slack RTM token		KB_TOKEN
-debug=bool	no	set debug mode	false	KB_DEBUG
-db string	no	path to sqlite database	./db.sqlite3	KB_DB
-leaderboardlimit int	no	the default amount of users to list in the leaderboard	10	KB_LEADERBOARDLIMIT
-maxpoints int	no	the maximum amount of points that users can give/take at once	6	KB_MAXPOINTS
-motivate=bool	no	toggle motivate.im support	true	KB_MOTIVATE
-blacklist string	no	may be passed multiple times blacklist string i.e. ignore karma commands for string	[]	KB_BLACKLIST
-reactji bool	no	use reactji (👍 and 👎) as reaction events	true	KB_REACTJI
-reactjis.upvote string	no	may be passed multiple times a list of reactjis to use for upvotes. for emojis with aliases, use the first name that is shown in the emoji popup	+1, thumbsup, thumbsup_all	KB_REACTJIS_UPVOTE
-reactjis.downvote string	no	may be passed multiple times a list of reactjis to use for downvotes. for emojis with aliases, use the first name that is shown in the emoji popup	-1, thumbsdown	KB_REACTJIS_DOWNVOTE
-alias string	no	may be passed multiple times alias different users to one user. syntax: -alias main++alias1++alias2++...++aliasN		KB_ALIAS
-selfkarma bool	no	allow users to add/remove karma to themselves	true	KB_SELFKARMA
-replytype string	no	whether to reply in channel (message), in a new thread under the user's message (thread), or only visible to the acting user (ephemeral)	message	KB_REPLYTYPE

In addition, see the table below for the options related to the web UI.

example: ./karmabot -token xoxb-abcdefg

It is recommended to pass karmabot's logs through humanlog. humanlog will format and color the JSON output as nice easy-to-read text.

Web UI

karmabot includes an optional web UI. The web UI uses TOTP tokens for authentication. While the token itself would only be valid for 30 seconds, once you have authenticated, you will stay so for 48 hours, after which your session will expire. This is not meant to be a fully-featured advanced authentication system, but rather a simple way to keep off people who do not belong to your Slack team.

How to use the Web UI

Requisites

1. download the www directory from the repo's root and place it in a directory that is accessible to karmabot.
2. run ./karmabot -token x -webui.listenaddr x -webui.path x. You may keep all the options set to x, as they will not be used at all. karmabot will generate a random TOTP key for you to use, print it, and exit. Copy that token.

Start karmabot

Once you have performed the steps detailed above, pass the necessary options to the karmabot binary. You can use environment variables as well, but any CLI options you pass will take precedence.

option	required?	description	default	env var
-webui.listenaddr string	yes	the address (host:port) on which to serve the web UI		KB_WEBUI_LISTENADDR
-webui.totp string	yes	the TOTP key (see above)		KB_WEBUI_TOTP
-webui.path string	yes	path to the www directory (see above)		KB_WEBUI_PATH
-webui.url string	no	the URL which karmabot should use to generate links to the web UI (without a trailing slash!)	defaults to http://webui.listenaddr	KB_WEBUI_URL

If done correctly, the web UI should be accessible on the webui.listenaddr that you have configured. The web UI will not be started if either of webui.listenaddr or webui.path are missing.

Usage

The web UI is authenticated, so you will have to generate authentication tokens through karmabot. You can access the web UI by typing karmabot web in the chat. karmabot will generate a TOTP token, append it to the webuiurl and send back the link. Click on the link and you should be authenticated for 48 hours.

Additionally, you may use also use the link provided in the Slack leaderboard (karmabot leaderboard) in order to log in and access the leaderboard.

karmabotctl

karmabot comes with a maintenance tool called karmabotctl. It can be used to perform certain tasks without having to run karmabot itself.

Commands

A list of all arguments for each command can be printed by running karmabotctl karma migrate --help. In addition to the arguments listed in the tables below, some commands may also require a <db> argument containing the path to the database file.

karma

command	arguments	description
add	<from> <to> <reason> <points>	add karma to a user
migrate	<from> <to>	move a user's karma to another user
reset	<user>	reset a user's karma
set	<user> <points>	set a user's karma to a specific number
throwback	<user>	get a karma throwback for a user

webui

command	arguments	description
serve	<debug> <leaderboardlimit> <totp> <path> <listenaddr> <url>	start a webserver
totp	<totp>	generate a TOTP token based on the passed secret

License

see ./LICENSE

Documentation

Index

• Variables
• type Bot
  • func New(config *Config) *Bot
  • func (b *Bot) DMUser(message, user string)
  • func (b *Bot) Listen()
  • func (b *Bot) SendMessage(message, channel, thread string)
  • func (b *Bot) SendMessageEphemeral(reply, channel, user, thread string)
  • func (b *Bot) SendReply(reply string, message *slack.MessageEvent)
  • func (b *Bot) SendReplyEphemeral(reply string, message *slack.MessageEvent)
• type ChatService
• type Config
• type Database
• type ReactjiConfig
• type SlackChatService
  • func (s SlackChatService) IncomingEventsChan() chan slack.RTMEvent
• type StringList
  • func (sl *StringList) Contains(value string) bool
  • func (sl *StringList) Set(value string) error
  • func (sl *StringList) String() string
• type UserAliases

Variables

var Version = "-dev"

Version is the current version of karmabot.

Types

type Bot

type Bot struct {
	Config *Config
}

A Bot is an instance of karmabot.

func New

func New(config *Config) *Bot

New returns a pointer to an new instance of karmabot.

func (*Bot) DMUser

func (b *Bot) DMUser(message, user string)

DMUser sends a message directly to a Slack user.

func (*Bot) Listen

func (b *Bot) Listen()

Listen starts listening for Slack messages and calls the appropriate handlers.

func (*Bot) SendMessage

func (b *Bot) SendMessage(message, channel, thread string)

SendMessage sends a message to a Slack channel.

func (*Bot) SendMessageEphemeral

func (b *Bot) SendMessageEphemeral(reply, channel, user, thread string)

SendMessageEphemeral sends an ephemeral message to a user

func (*Bot) SendReply

func (b *Bot) SendReply(reply string, message *slack.MessageEvent)

SendReply sends a reply to a message, either as a new message in the channel or a thread (configurable)

func (*Bot) SendReplyEphemeral

func (b *Bot) SendReplyEphemeral(reply string, message *slack.MessageEvent)

SendReplyEphemeral sends a reply to a message as an ephemeral message to the user

type ChatService

type ChatService interface {
	// IncomingEventsChan returns a channel of real-time events.
	IncomingEventsChan() chan slack.RTMEvent

	// NewOutgoingMessage constructs a new OutgoingMessage using the provided text and channel.
	NewOutgoingMessage(text string, channel string, options ...slack.RTMsgOption) *slack.OutgoingMessage

	// SendMessage sends the provided *OutgoingMessage.
	SendMessage(msg *slack.OutgoingMessage)

	// OpenIMChannel opens a new direct-message channel with the specified user.
	// It returns some status information, and the channel ID.
	OpenIMChannel(user string) (bool, bool, string, error)

	// GetUserInfo retrieves the complete user information for the specified username.
	GetUserInfo(user string) (*slack.User, error)

	// PostEphemeral sends an ephemeral message to a user in a channel.
	PostEphemeral(channelID, userID string, options ...slack.MsgOption) (string, error)
}

ChatService is an abstraction around Slack, mostly designed for use in tests.

type Config

type Config struct {
	Slack                       ChatService
	Debug, Motivate, SelfKarma  bool
	MaxPoints, LeaderboardLimit int
	Log                         *log.Log
	UI                          ui.Provider
	DB                          Database
	UserBlacklist               StringList
	Aliases                     UserAliases
	Reactji                     *ReactjiConfig
	ReplyType                   string
}

Config contains all the necessary configs for karmabot.

type Database

type Database interface {
	// InsertPoints persistently records that points have been given or deducted.
	InsertPoints(points *database.Points) error

	// GetUser returns information about a user, including their current number of points.
	GetUser(name string) (*database.User, error)

	// GetLeaderboard returns the top X users with the most points, in order.
	GetLeaderboard(limit int) (database.Leaderboard, error)

	// GetTotalPoints returns the total number of points transferred across all users.
	GetTotalPoints() (int, error)

	// GetThrowback returns a random karma operation on a specific user.
	GetThrowback(user string) (*database.Throwback, error)
}

Database is an abstraction around the database, mostly designed for use in tests.

type ReactjiConfig

type ReactjiConfig struct {
	Enabled          bool
	Upvote, Downvote StringList
}

ReactjiConfig contains the configuration for reactji-based votes

type SlackChatService

type SlackChatService struct {
	slack.RTM
}

SlackChatService is an implementation of ChatService using github.com/nlopes/slack.

func (SlackChatService) IncomingEventsChan

func (s SlackChatService) IncomingEventsChan() chan slack.RTMEvent

IncomingEventsChan returns a channel of real-time messaging events.

type StringList

type StringList map[string]struct{}

StringList is an object that accepts multiple strings and implements flag.Value

func (*StringList) Contains

func (sl *StringList) Contains(value string) bool

Contains checks if the list contains a certain item

func (*StringList) Set

func (sl *StringList) Set(value string) error

Set receives a string and appends it to the internal map

func (*StringList) String

func (sl *StringList) String() string

type UserAliases

type UserAliases map[string]string

UserAliases is a map of alias -> main username