reddit-context-bot
Context Bot is an event-based, reddit moderation bot built on top of snoowrap and written in typescript.
It is designed to help fill in the gaps for automoderator in regard to more complex behavior with a focus on user-history based moderation.
An example of the above that Context Bot can do now:
- On a new submission, check if the user has also posted the same link in N number of other subreddits within a timeframe/# of posts
- On a new submission or comment, check if the user has had any activity (sub/comment) in N set of subreddits within a timeframe/# of posts
In either instance Context Bot can then perform any action a moderator can (comment, report, remove, lock, etc...) against that user, comment, or submission.
Some feature highlights:
- Simple rule-action behavior can be combined to create any level of complexity in behavior
- One instance can handle managing many subreddits (as many as it has moderator permissions in!)
- Per-subreddit configuration is handled by JSON stored in the subreddit wiki
- Any text-based actions (comment, submission, message, etc...) can be configured via a wiki page or raw text in JSON
- All text-based actions support mustache templating
- History-based rules support multiple "valid window" types -- ISO 8601 Durations, Day.js Durations, and submission/comment count limits.
- All rules support skipping behavior based on author criteria -- name, css flair/text, and moderator status
- Docker container support (coming soon...)
Table of Contents
How It Works
Context Bot's configuration is made up of an array of Checks. Each Check consists of :
Kind
Is this check for a submission or comment?
Rules
A list of Rule objects to run against the activity. If any Rule object is triggered by the activity then the Check runs its Actions
Actions
A list of Action objects that describe what the bot should do with the activity or author of the activity. The bot will run all Actions in this list.
The Checks for a subreddit are split up into Submission Checks and Comment Checks based on their kind. Each list of checks is run independently based on when events happen (submission or comment).
When an event occurs all Checks of that type are run in the order they were listed in the configuration. When one check is triggered (an action is performed) the remaining checks will not be run.
Installation
Locally
Clone this repository somewhere and then install from the working directory
git clone https://github.com/FoxxMD/reddit-context-bot.git .
cd reddit-context-bot
npm install
Docker
foxxmd/reddit-context-bot:latest
Adding environmental variables to your docker run command will pass them through to the app EX:
docker run -e "CLIENT_ID=myId" ... foxxmd/reddit-context-bot
Configuration
Context Bot's configuration schema conforms to JSON Schema Draft 7.
I suggest using Atlassian JSON Schema Viewer (direct link) so you can view all documentation while also interactively writing and validating your config! From there you can drill down into any object, see its requirements, view an example JSON document, and live-edit your configuration on the right-hand side.
Action Templating
Actions that can submit text (Report, Comment) will have their content values run through a Mustache Template. This means you can insert data generated by Rules into your text before the Action is performed.
See here for a cheatsheet and here for a more thorough tutorial.
All Actions with content have access to this data:
{
item: {
kind: 'string', // the type of item (comment/submission)
author: 'string', // name of the item author (reddit user)
permalink: 'string', // a url to the item
url: 'string', // if the item is a Submission then its URL (external for link type submission, reddit link for self-posts)
title: 'string', // if the item is a Submission, then the title of the Submission
},
rules: {
// contains all rules that were run and are accessible using the name, lowercased, with all spaces/dashes/underscores removed
}
}
The properties of rules are accessible using the name, lower-cased, with all spaces/dashes/underscores. If no name is given kind is used as name Example:
"rules": [
{
"name": "My Custom-Recent Activity Rule", // mycustomrecentactivityrule
"kind": "recentActivity"
},
{
// name = repeatsubmission
"kind": "repeatSubmission",
}
]
To see what data is available for individual Rules consult the schema for each Rule.
Quick Templating Tutorial
As a quick example for how you will most likely be using templating -- wrapping a variable in curly brackets, {{variable}}, will cause the variable value to be rendered instead of the brackets:
myVariable = 50;
myOtherVariable = "a text fragment"
template = "This is my template, the variable is {{myVariable}}, my other variable is {{myOtherVariable}}, and that's it!";
console.log(Mustache.render(template, {myVariable});
// will render...
"This is my template, the variable is 50, my other variable is a text fragment, and that's it!";
Note: When accessing an object or its properties you must use dot notation
const item = {
aProperty: 'something',
anotherObject: {
bProperty: 'something else'
}
}
const content = "My content will render the property {{item.aProperty}} like this, and another nested property {{item.anotherObject.bProperty}} like this."
Example Config
Below is a configuration fulfilling the example given at the start of this readme:
Click to expand configuration
{
"checks": [
{
"name": "repeatSpam",
"kind": "submission",
"rules": [
{
"kind": "repeatSubmission",
"gapAllowance": 2,
"threshold": 10
}
],
"actions": [
{
"kind": "remove"
},
{
"kind": "comment",
"content": "Thank you for your submission but we do not allow mass crossposting. Your submission has been removed",
"distingish": true
}
]
},
{
"name": "selfPromoActivity",
"kind": "submission",
"rules": [
{
"kind": "recentActivity",
"thresholds": [
{
"subreddits": [
"YouTubeSubscribeBoost",
"AdvertiseYourVideos"
]
}
]
}
],
"actions": [
{
"kind": "report",
"content": "User posted link {{rules.recentactivity.totalCount}} times in {{rules.recentactivity.subCount}} SP subs: {{rules.recentactivity.summary}}"
}
]
}
]
}
Usage
npm run start [list,of,subreddits] [...--options]
CLI options take precedence over environmental variables
| CLI | Environmental Variable | Required | Description |
|---|---|---|---|
| [First Argument] | No | Comma-deliminated list of subreddits to run on if you don't want to run all the account has access to. | |
| --clientId | CLIENT_ID | Yes | Your reddit application client id |
| --clientSecret | CLIENT_SECRET | Yes | Your reddit application client secret |
| --accessToken | ACCESS_TOKEN | Yes | A valid access token retrieved from completing the oauth flow for a user with your application. |
| --refreshToken | REFRESH_TOKEN | Yes | A valid refresh token retrieved from completing the oauth flow for a user with your application. |
| --logDir | LOG_DIR | No | The absolute path to where logs should be stored. use false to turn off log files. Defaults to CWD/logs |
| --logLevel | LOG_LEVEL | No | The minimum level to log at. Uses Winston Log Levels. Defaults to info |
| --wikiConfig | WIKI_CONFIG | No | The location of the bot configuration in the subreddit wiki. Defaults to botconfig/contextbox |
Reddit App??
To use this bot you must do two things:
- Create a reddit application
- Authenticate that application to act as a user (login to the application with an account)
Create Application
Visit your reddit preferences and at the bottom of the page go through the create an(other) app process.
- Choose script
- For redirect uri use https://not-an-aardvark.github.io/reddit-oauth-helper/
- Write down your Client ID and Client Secret somewhere
Authenticate an Account
Visit https://not-an-aardvark.github.io/reddit-oauth-helper/
- Input your Client ID and Client Secret in the text boxes with those names.
- Choose scopes. It is very important you check everything on this list or Context Bot will not work correctly
- edit
- flair
- history
- identity
- modcontributors
- modflair
- modposts
- modself
- mysubreddits
- read
- report
- submit
- wikiread
- Click *Generate tokens, you will get a popup asking you to approve access (or login) -- the account you approve access with is the account that Bot will control.
- After approving an Access Token and Refresh Token will be shown at the bottom of the page. Write these down.
You should now have all the information you need to start the bot.