{"id":13409462,"url":"https://github.com/alexandre-normand/slackscot","last_synced_at":"2025-03-14T14:31:25.388Z","repository":{"id":45996726,"uuid":"44722940","full_name":"alexandre-normand/slackscot","owner":"alexandre-normand","description":"Slack bot core/framework written in Go with support for reactions to message updates/deletes","archived":false,"fork":false,"pushed_at":"2023-02-25T04:37:17.000Z","size":598,"stargazers_count":56,"open_issues_count":3,"forks_count":10,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-07-31T20:36:56.215Z","etag":null,"topics":["bot","golang","golang-library","golang-package","mascot","montreal-expos","slack","slack-bot","slackbot"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alexandre-normand.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2015-10-22T04:54:55.000Z","updated_at":"2023-09-18T15:27:30.000Z","dependencies_parsed_at":"2024-01-08T14:30:45.566Z","dependency_job_id":"6c4c0250-49bb-4321-8ff3-31bd6b22017f","html_url":"https://github.com/alexandre-normand/slackscot","commit_stats":null,"previous_names":[],"tags_count":98,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexandre-normand%2Fslackscot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexandre-normand%2Fslackscot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexandre-normand%2Fslackscot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexandre-normand%2Fslackscot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexandre-normand","download_url":"https://codeload.github.com/alexandre-normand/slackscot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243593395,"owners_count":20316177,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bot","golang","golang-library","golang-package","mascot","montreal-expos","slack","slack-bot","slackbot"],"created_at":"2024-07-30T20:01:01.037Z","updated_at":"2025-03-14T14:31:20.430Z","avatar_url":"https://github.com/alexandre-normand.png","language":"Go","funding_links":[],"categories":["机器人相关","Bot Building","Bot建设","Uncategorized","机器人相关` 构建和使用机器人的库`"],"sub_categories":["Contents","Free e-books"],"readme":"[![License](https://img.shields.io/github/license/alexandre-normand/slackscot.svg)](LICENSE)\n[![GoDoc](https://godoc.org/github.com/alexandre-normand/slackscot?status.svg)](https://pkg.go.dev/github.com/alexandre-normand/slackscot?tab=doc)\n[![Build](https://github.com/alexandre-normand/slackscot/workflows/Go/badge.svg)](https://github.com/alexandre-normand/slackscot/actions)\n[![Go Report Card](https://goreportcard.com/badge/github.com/alexandre-normand/slackscot)](https://goreportcard.com/report/github.com/alexandre-normand/slackscot)\n[![Test Coverage](https://api.codeclimate.com/v1/badges/9fe1722ab2f31036c44c/test_coverage)](https://codeclimate.com/github/alexandre-normand/slackscot/test_coverage)\n[![Maintainability](https://api.codeclimate.com/v1/badges/9fe1722ab2f31036c44c/maintainability)](https://codeclimate.com/github/alexandre-normand/slackscot/maintainability)\n[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go) \n[![Latest Version](https://img.shields.io/github/tag/alexandre-normand/slackscot.svg?label=version)](https://github.com/alexandre-normand/slackscot/releases)\n\n![logo.svg](logo.svg)\n\n![name.svg](name.svg)\n\n\u003c!-- MarkdownTOC --\u003e\n\n- [Overview](#overview)\n- [Requirements](#requirements)\n- [Features](#features)\n- [Demo](#demo)\n- [The Name](#the-name)\n- [Concepts](#concepts)\n- [Create Your Own Slackscot](#create-your-own-slackscot)\n  - [Assembling the Parts and Bringing Your `slackscot` to Life](#assembling-the-parts-and-bringing-your-slackscot-to-life)\n  - [Configuration Example](#configuration-example)\n  - [Creating Your Own Plugins](#creating-your-own-plugins)\n- [Contributing](#contributing)\n  - [Open-telemetry integration](#open-telemetry-integration)\n- [Some Credits](#some-credits)\n\n\u003c!-- /MarkdownTOC --\u003e\n\n# Overview \n\n`Slackscot` is a [slack](https://slack.com) `bot` core written in [Go](golang.org). \nThink of it as the assembly kit to making your own friendly `slack` `bot`. It comes\nwith a set of plugins you might enjoy and a friendly `API` for you to realize\nyour ambitious dreams (if you dreams include this sort of thing).\n\n# Requirements\n\n`Go 1.11` or above is required, mostly for [go module support](https://github.com/golang/go/wiki/Modules). \n\n# Features \n\n*   Support for reactions to message updates. `slackscot` does the following:\n    *   Keeps track of plugin action responses and the message that triggered\n        them\n\n    *   On message updates:\n        1.  Update responses for each triggered action\n\n        2.  Delete responses that aren't triggering anymore (or result in \n            errors during the message update)\n\n    *   On deletion of triggering messages, responses are also deleted\n\n    *   *Limitation*: Sending a `message` automatically splits it into \n        multiple slack messages when it's too long. When updating messages,\n\t    this spitting doesn't happen and results in an `message too long` \n\t    error. Effectively, the last message in the initial response might get\n\t    `deleted` as a result. Handling of this could be better but that is \n\t    the current limitation 😕\n\n*   Support for threaded replies to user message with option to also \n    `broadcast` on channels (disabled by `default`). \n    See [configuration example](#configuration-example) below where \n    both are enabled. \n    *   Plugin actions may also explicitely reply in threads with/without\n        broadcasting via [AnswerOption](answer.go)\n\n*   Concurrent processing of unrelated messages with guarantees of proper \n    ordering of message updates/deletions\n\n*   Simple extensible storage `API` for persistence in two flavors: \n    `StringStorer` and `BytesStorer`. Both are basic `key:value` maps. \n    A default file-based implementation is provided backed by\n    [leveldb](https://github.com/syndtr/goleveldb)\n\n*   Implementation of `StringStorer` backed by\n    [Google Cloud Datastore](https://cloud.google.com/datastore/docs/reference/libraries).\n    See [datastoredb's godoc](https://godoc.org/github.com/alexandre-normand/slackscot/store/datastoredb) \n    for documentation, usage and example.\n\n*   In-memory implementation of `StringStorer` wrapping any `StringStorer` implementation\n    to offer low-latency and potentially cost-saving storage implementation well-suited for\n    small datasets. Plays well with cloud storage like the \n    [datastoredb]((https://godoc.org/github.com/alexandre-normand/slackscot/store/datastoredb) \n    See [inmemorydb's godoc](https://godoc.org/github.com/alexandre-normand/slackscot/store/inmemorydb) \n    for documentation, usage and example.\n\n*   Support for various configuration sources/formats via \n    [viper](https://github.com/spf13/viper)\n\n*   Support for various ways to implement functionality: \n    1.  `scheduled actions`: run something every second, minute, hour, week. \n        [Oh Monday](plugins/ohmonday.go) is a plugin that demos this by \n        sending a `Monday` greeting every Monday at 10am (or the time you \n        configure it to).\n    2.  `commands`: respond to a _command_ directed at your `slackscot`. That \n        means something like `@slackscot help` or a direct message `help`\n        sent to `slackscot`.\n    3.  `hear actions` (aka \"listeners\"): actions that evaluated for a match\n        on every message that `slackscot` hears. You'll want to make sure\n        your `Match` function isn't too heavy. An example is the \"famous\" \n        [finger quoter plugin](plugins/fingerquoter.go)\n\n*   *Experimental and subject to change*: \n    Testing functions to help validate plugin action behavior (see example in \n    [triggerer_test.go](plugins/triggerer_test.go)). Testing functions\n    are found in \n    [assertplugin](https://godoc.org/github.com/alexandre-normand/slackscot/test/assertplugin) and \n    [assertanswer](https://godoc.org/github.com/alexandre-normand/slackscot/test/assertanswer)\n\n*   Built-in `help` plugin supporting a decently formatted help message\n    as a command listing all plugins' actions. If you'd like some actions \n    to not be shown in the help, you can set `Hidden` to `true` in \n    its `ActionDefinition` (especially useful for `hear actions`)\n\n*   The plugin interface as a logical grouping of one or many `commands` and \n    `hear actions` and/or `scheduled actions` \n\n*   Support for injected services providing plugins easy access to an optionally caching \n    `user info` and a `logger`. \n\n# Demo\n\n*   `slackscot` deleting a triggered reaction after seeing a message updated \n    that caused the  first action to *not* trigger anymore and a new action \n    to now trigger (it makes sense when you see it)\n\n![different-action-triggered-on-message-update](https://www.dropbox.com/s/r325jn1sqb7a93g/slackscot-update-message-trigger-different-action.gif?raw=1)\n\n*   `slackscot` updating a triggered reaction after seeing a triggering message \n    being updated\n\n![same-action-answer-update-on-message-update](https://www.dropbox.com/s/ge8p38bl977ugld/slackscot-update-same-action.gif?raw=1)\n\n*   `slackscot` deleting a reaction after seeing the triggering message being\n    deleted\n\n![reaction-deletion-on-message-delete](https://www.dropbox.com/s/bwhq20m1b2obvx6/slackscot-delete-message-delete-answers.gif?raw=1)\n\n*   `slackscot` threaded replies enabled (with `broadcast =\u003e on`)\n\n![threaded-reply-with-broadcast](https://www.dropbox.com/s/yfinvpbrla9pth8/slackscot-threaded-replies-with-broadcast.gif?raw=1)\n\n# The Name\n\nThe first concrete bot implementation using this code was \n[youppi](https://github.com/alexandre-normand/youppi), named after the \n[great mascot](https://en.wikipedia.org/wiki/Youppi!) of the Montreal Expos \nand, when the Expos left Montreal, the Montreal Canadiens. \n\n`Slackscot` is a variation on the expected theme of *slackbot* with the \nimplication that this is the core to *more* than just a regular `bot`. \nYou know, a friendly company *mascot* that hangs out on your `slack`. \n\n# Concepts\n\n*   `Commands`: commands are well-defined actions with a format. `Slackscot` \n    handles all direct messages as implicit commands as well as \n    `@mention \u003ccommand\u003e` on channels. Responses to commands are directed \n    to the person who invoked it.\n\n*   `Hear actions`: those are listeners that can potentially match on any \n    message sent on channels that `slackscot` is a member of. This can \n    include actions that will randomly generate a response. Note that \n    responses are not automatically directed to the person who authored \n    the message triggering the response (although an implementation is \n    free to use the user id of the triggering message if desired). \n\n# Create Your Own Slackscot\n\n`Slackscot` provides the pieces to make your mascot but you'll have to \nassemble them for him/her to come alive. The easiest to get started is\nto look at a real example: [youppi](https://github.com/alexandre-normand/youppi).\n\n![youppi running](https://media.giphy.com/media/4K1HwWtmvT07sW7enp/giphy.gif)\n\nThe [godoc](https://godoc.org/github.com/alexandre-normand/slackscot) is also a \ngood reference especially if you're looking to implement something like a \nnew implementation of the [storer interfaces](https://godoc.org/github.com/alexandre-normand/slackscot/store).\n\n## Assembling the Parts and Bringing Your `slackscot` to Life\n\nHere's an abbreviated example of how [youppi](https://github.com/alexandre-normand/youppi) \n[does it](https://github.com/alexandre-normand/youppi/blob/master/youppi.go):\n\n```go\npackage main\n\nimport (\n\t\"github.com/alexandre-normand/slackscot\"\n\t\"github.com/alexandre-normand/slackscot/config\"\n\t\"github.com/alexandre-normand/slackscot/plugins\"\n\t\"github.com/alexandre-normand/slackscot/store\"\n\t\"github.com/spf13/viper\"\n\t\"gopkg.in/alecthomas/kingpin.v2\"\n\t\"log\"\n\t\"os\"\n\t\"io\"\n)\n\nconst (\n\tname           = \"youppi\"\n)\n\nfunc main() {\n\tkingpin.Version(VERSION)\n\tkingpin.Parse()\n\n\t// TODO: initialize storer implementations required by plugins and do any other initialization \n\t// required\n\t...\n\n\t// This is the where we create youppi with all of its plugins\n\tyouppi, err := slackscot.NewBot(name, v, options...).\n\t\tWithPlugin(plugins.NewKarma(karmaStorer)).\n\t\tWithPlugin(plugins.NewTriggerer(triggererStorer)).\n\t\tWithConfigurablePluginErr(plugins.FingerQuoterPluginName, func(conf *config.PluginConfig) (p *slackscot.Plugin, err error) { return plugins.NewFingerQuoter(conf) }).\n\t\tWithConfigurablePluginCloserErr(plugins.EmojiBannerPluginName, func(conf *config.PluginConfig) (c io.Closer, p *slackscot.Plugin, err error) {\n\t\t\treturn plugins.NewEmojiBannerMaker(conf)\n\t\t}).\n\t\tWithConfigurablePluginErr(plugins.OhMondayPluginName, func(conf *config.PluginConfig) (p *slackscot.Plugin, err error) { return plugins.NewOhMonday(conf) }).\n\t\tWithPlugin(plugins.NewVersionner(name, version)).\n\t\tBuild()\n\tdefer youppi.Close()\n\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\terr = youppi.Run()\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n}\n```\n\n## Configuration Example\n\nYou'll also need to define your configuration for the `core`, used \nbuilt-in plugins and any configuration required by your own custom plugins \n(not shown here). `Slackscot` uses \n[viper](https://github.com/spf13/viper) for loading configuration\nwhich means that you are free to use a different file format \n(`yaml`, `toml`, `env variables`, etc.) as desired. \n\n```json\n{\n   \"token\": \"your-slack-bot-token\",\n   \"debug\": false,\n   \"responseCacheSize\": 5000,\n   \"userInfoCacheSize\": 0,\n   \"maxAgeHandledMessages\": 86400,\n   \"timeLocation\": \"America/Los_Angeles\",\n   \"storagePath\": \"/your-path-to-bot-home\",\n   \"replyBehavior\": {\n      \"threadedReplies\": true,\n      \"broadcastThreadedReplies\": true\n   },\n   \"plugins\": {\n      \"ohMonday\": {\n   \t     \"channelIDs\": [\"slackChannelId\"]\n      },\n      \"fingerQuoter\": {\n         \"frequency\": \"100\",\n         \"channelIDs\": []\n      },\n      \"emojiBanner\": {\n         \"figletFontUrl\": \"http://www.figlet.org/fonts/banner.flf\"\n      }\n   }\n}\n```\n\n## Creating Your Own Plugins\n\nIt might be best to look at examples in this repo to guide you through it:\n\n*   The simplest plugin with a single `command` is the [versioner](plugins/versioner.go)\n*   One example of `scheduled actions` is [oh monday](plugins/ohmonday.go)\n*   One example of a mix of `hear actions` / `commands` that also uses the\n    `store` api for persistence is the [karma](plugins/karma.go)\n\n# Contributing\n\n1.   Fork it (preferrably, outside the `GOPATH` as per the new \n     [go modules guidelines](https://github.com/golang/go/wiki/Modules#how-to-install-and-activate-module-support))\n2.   Make your changes, commit them (don't forget to `go build ./...` and \n     `go test ./...`) and push your branch to your fork\n3.   Open a PR and fill in the template (you don't have to but I'd appreciate context)\n4.   Check the `code climate` and `travis` PR builds. You might have to fix things and\n     there's no shame if you do. I probably won't merge something that doesn't pass\n     `CI` build but I'm willing to help to get it to pass 🖖.  \n\n## Open-telemetry integration\n\n`Slackscot` now supports integration with [opentelemetry](https://opentelemetry.io/). To aid with the addition\nof new metrics, you can find a [gowrap](https://github.com/hexdigest/gowrap) template [here](./opentelemetry.template). \nTo add a metrics to a new interface, you can do something like\n\n```bash\ngowrap gen -p . -i \u003cinterfaceName\u003e -t opentelemetry.template -o \u003cinterfaceName\u003emetrics.go\n```\n\nWhen updating the [template](./opentelemetry.template), you should consider running `go generate` in order to refresh\nthe already generated files with the template changes. \n\n# Some Credits\n`slackscot` uses [Norberto Lopes](https://github.com/nlopes)'s \n[Slack API Integration](https://github.com/nlopes/slack) found at \n[https://github.com/nlopes/slack](https://github.com/nlopes/slack). The core\nfunctionality of the bot is previously used \n[James Bowman](https://github.com/james-bowman)'s \n[Slack RTM API integration](https://github.com/james-bowman/slack) and \nwas heavily inspired by [talbot](https://github.com/james-bowman/talbot), \nalso written by [James Bowman](https://github.com/james-bowman). \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexandre-normand%2Fslackscot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexandre-normand%2Fslackscot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexandre-normand%2Fslackscot/lists"}