Merge branch 'edge'

* compact the calls/miss stats into one line
* combine cache type stats and description
* improve cache tips documentation

.dockerignore

@@ -4,3 +4,5 @@ Dockerfile
 .gitignore
 .git
 src/logs
+/docs
+.github

.github/workflows/dockerhub.yml

@@ -0,0 +1,51 @@
+name: Publish Docker image to Dockerhub
+
+on:
+  push:
+    branches:
+      - 'master'
+      - 'edge'
+    tags:
+      - 'v*.*.*'
+    # don't trigger if just updating docs
+    paths-ignore:
+      - '**.md'
+
+jobs:
+  push_to_registry:
+    name: Push Docker image to Docker Hub
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v2
+      
+      - name: Log in to Docker Hub
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@f054a8b539a109f9f41c372932f1ae047eff08c9
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+      
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v3
+        with:
+          images: foxxmd/context-mod
+          # generate Docker tags based on the following events/attributes
+          tags: |
+            type=raw,value=latest,enable=${{ endsWith(github.ref, 'master') }}
+            type=ref,event=branch,enable=${{ !endsWith(github.ref, 'master') }}
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+          flavor: |
+            latest=false
+      
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v2
+        with:
+          context: .
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+

Dockerfile

@@ -24,4 +24,8 @@ RUN mkdir -p $log_dir
 VOLUME $log_dir
 ENV LOG_DIR=$log_dir
 
+ARG webPort=8085
+ENV PORT=$webPort
+EXPOSE $PORT
+
 CMD [ "node", "src/index.js", "run" ]

README.md

@@ -1,10 +1,8 @@
-# reddit-context-bot
-
-[![Latest Release](https://img.shields.io/github/v/release/foxxmd/reddit-context-bot)](https://github.com/FoxxMD/reddit-context-bot/releases)
+[![Latest Release](https://img.shields.io/github/v/release/foxxmd/context-mod)](https://github.com/FoxxMD/context-mod/releases)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Docker Pulls](https://img.shields.io/docker/pulls/foxxmd/reddit-context-bot)](https://hub.docker.com/r/foxxmd/reddit-context-bot)
+[![Docker Pulls](https://img.shields.io/docker/pulls/foxxmd/context-mod)](https://hub.docker.com/r/foxxmd/context-mod)
 
-**Context Bot** is an event-based, [reddit](https://reddit.com) moderation bot built on top of [snoowrap](https://github.com/not-an-aardvark/snoowrap) and written in [typescript](https://www.typescriptlang.org/).
+**Context Mod** (CM) is an event-based, [reddit](https://reddit.com) moderation bot built on top of [snoowrap](https://github.com/not-an-aardvark/snoowrap) and written in [typescript](https://www.typescriptlang.org/).
 
 It is designed to help fill in the gaps for [automoderator](https://www.reddit.com/wiki/automoderator/full-documentation) in regard to more complex behavior with a focus on **user-history based moderation.**
 
@@ -17,27 +15,32 @@ An example of the above that Context Bot can do now:
 
 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](https://mustache.github.io) templating
+* One instance can manage all moderated subreddits for the authenticated account
+* **Per-subreddit configuration** is handled by JSON stored in the subreddit wiki
+* Any text-based actions (comment, submission, message, usernotes, ban, etc...) can be configured via a wiki page or raw text in JSON and support [mustache](https://mustache.github.io) [templating](/docs/actionTemplating.md)
 * History-based rules support multiple "valid window" types -- [ISO 8601 Durations](https://en.wikipedia.org/wiki/ISO_8601#Durations), [Day.js Durations](https://day.js.org/docs/en/durations/creating), and submission/comment count limits.
-* All rules support skipping behavior based on author criteria -- name, css flair/text, and moderator status
-* Rules and Actions support named references so you write rules/actions once and reference them anywhere
-* User-configurable global/subreddit-level API caching
+* Support Activity skipping based on:
+  * Author criteria (name, css flair/text, age, karma, moderator status, and [Toolbox User Notes](https://www.reddit.com/r/toolbox/wiki/docs/usernotes))
+  * Activity state (removed, locked, distinguished, etc.)
+* Rules and Actions support named references (write once, reference anywhere)
+* Global/subreddit-level **API caching**
+* Support for [Toolbox User Notes](https://www.reddit.com/r/toolbox/wiki/docs/usernotes) as criteria or Actions (writing notes)
 * Docker container support
+* Event notification via Discord
+* **Web interface** for monitoring and administration
 
 # Table of Contents
 
 * [How It Works](#how-it-works)
-* [Installation](#installation)
-* [Configuration](#configuration)
-  * [Examples](#examples)
-* [Usage](#usage)
+* [Getting Started](#getting-started)
+* [Configuration And Documentation](#configuration-and-documentation)
+* [Web UI and Screenshots](#web-ui-and-screenshots)
 
 ### How It Works
 
-Context Bot's configuration is made up of an array of **Checks**. Each **Check** consists of :
+Each subreddit using the RCB bot configures its behavior via their own wiki page. 
+
+When a monitored **Event** (new comment/submission, new modqueue item, etc.) is detected the bot runs through a list of **Checks** to determine what to do with the **Activity** from that Event. Each **Check** consists of :
 
 #### Kind
 
@@ -45,190 +48,63 @@ 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**
+A list of **Rule** objects to run against the **Activity**. Triggered Rules can cause the whole Check to trigger and run 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.
+A list of **Action** objects that describe what the bot should do with the **Activity** or **Author** of the activity (comment, remove, approve, etc.). 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.
+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
+___
 
+[Learn more about the RCB lifecycle and core concepts in the docs.](/docs#how-it-works)
 
-### Locally
+## Getting Started
 
-Clone this repository somewhere and then install from the working directory
+#### Operators
 
-```bash
-git clone https://github.com/FoxxMD/reddit-context-bot.git .
-cd reddit-context-bot
-npm install
-```
+This guide is for users who want to **run their own bot on a ContextMod instance.**
 
-### [Docker](https://hub.docker.com/r/foxxmd/reddit-context-bot)
+See the [Operator's Getting Started Guide](/docs/gettingStartedOperator.md)
 
-```
-foxxmd/reddit-context-bot:latest
-```
+#### Moderators
 
-Adding [**environmental variables**](#usage) to your `docker run` command will pass them through to the app EX:
-```
-docker run -e "CLIENT_ID=myId" ... foxxmd/reddit-context-bot
-```
+This guide is for **reddit moderators** who want to configure an existing CM bot to run on their subreddit.
 
-### [Heroku Quick Deploy](https://heroku.com/about)
-[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://dashboard.heroku.com/new?template=https://github.com/FoxxMD/reddit-context-bot)
+See the [Moderator's Getting Started Guide](/docs/gettingStartedMod.md)
 
+## Configuration and Documentation
 
-## Configuration
+Context Bot's configuration can be written in JSON, [JSON5](https://json5.org/) or YAML. Its schema conforms to [JSON Schema Draft 7](https://json-schema.org/). Additionally, many **operator** settings can be passed via command line or environmental variables.
 
-Context Bot's configuration can be written in JSON or [JSON5](https://json5.org/). It's [schema](/src/Schema/App.json) conforms to [JSON Schema Draft 7](https://json-schema.org/).
+* For **operators** (running the bot instance) see the [Operator Configuration](/docs/operatorConfiguration.md) guide
+* For **moderators** consult the [app schema and examples folder](/docs/#configuration-and-usage)
 
-I suggest using [Atlassian JSON Schema Viewer](https://json-schema.app/start) ([direct link](https://json-schema.app/view/%23?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Freddit-context-bot%2Fmaster%2Fsrc%2FSchema%2FApp.json)) 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.
+[**Check the full docs for in-depth explanations of all concepts and examples**](/docs)
 
-### Examples
+## Web UI and Screenshots
 
-Read through the [Examples](/examples) section for a thorough introduction to all the **Rules**, in-depth concepts, and sample configuration files.
+RCB comes equipped with a web interface designed for use by both moderators and bot operators. Some feature highlights:
 
-### Action Templating
+* Authentication via Reddit OAuth -- only accessible if you are the bot operator or a moderator of a subreddit the bot moderates
+* Monitor API usage/rates
+* Monitoring and administration **per subreddit:**
+  * Start/stop/pause various bot components
+  * View statistics on bot usage (# of events, checks run, actions performed) and cache usage
+  * View various parts of your subreddit's configuration and manually update configuration
+  * View **real-time logs** of what the bot is doing on your subreddit
+  * **Run bot on any permalink**
 
-Actions that can submit text (Report, Comment) will have their `content` values run through a [Mustache Template](https://mustache.github.io/). This means you can insert data generated by Rules into your text before the Action is performed.
+![Subreddit View](docs/screenshots/subredditStatus.jpg)
 
-See here for a [cheatsheet](https://gist.github.com/FoxxMD/d365707cf99fdb526a504b8b833a5b78) and [here](https://www.tsmean.com/articles/mustache/the-ultimate-mustache-tutorial/) for a more thorough tutorial.
+Additionally, a helper webpage is available to help initial setup of your bot with reddit's oauth authentication. [Learn more about using the oauth helper.](docs/botAuthentication.md#cm-oauth-helper-recommended)
 
-All Actions with `content` have access to this data:
-
-```json5
-{
-    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": "repeatActivity",
-  }
-]
-```
-
-**To see what data is available for individual Rules [consult the schema](#configuration) for each Rule.**
-
-#### Quick Templating Tutorial
-
-<details>
-
-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."
-```
-</details>
-
-## Usage
-
-```
-Usage: index [options] [command]
-
-Options:
-  -c, --clientId <id>                          Client ID for your Reddit application (default: process.env.CLIENT_ID)
-  -e, --clientSecret <secret>                  Client Secret for your Reddit application (default: process.env.CLIENT_SECRET)
-  -a, --accessToken <token>                    Access token retrieved from authenticating an account with your Reddit Application (default: process.env.ACCESS_TOKEN)
-  -r, --refreshToken <token>                   Refresh token retrieved from authenticating an account with your Reddit Application (default: process.env.REFRESH_TOKEN)
-  -s, --subreddits <list...>                   List of subreddits to run on. Bot will run on all subs it has access to if not defined (default: process.env.SUBREDDITS (comma-seperated))
-  -d, --logDir <dir>                           Absolute path to directory to store rotated logs in (default: process.env.LOG_DIR || process.cwd()/logs)
-  -l, --logLevel <level>                       Log level (default: process.env.LOG_LEVEL || info)
-  -w, --wikiConfig <path>                      Relative url to contextbot wiki page EX https://reddit.com/r/subreddit/wiki/<path> (default: process.env.WIKI_CONFIG || 'botconfig/contextbot')
-  --snooDebug                                  Set Snoowrap to debug (default: process.env.SNOO_DEBUG || false)
-  --authorTTL <ms>                             Set the TTL (ms) for the Author Activities shared cache (default: process.env.AUTHOR_TTL || 10000)
-  --heartbeat <s>                              Interval, in seconds, between heartbeat logs. Set to 0 to disable (default: process.env.HEARTBEAT || 300)
-  --apiLimitWarning <remaining>                When API limit remaining (600/10min) is lower than this value log statements for limit will be raised to WARN level (default: process.env.API_REMAINING || 250)
-  --dryRun                                     Set dryRun=true for all checks/actions on all subreddits (overrides any existing) (default: process.env.DRYRUN)
-  --disableCache                               Disable caching for all subreddits (default: process.env.DISABLE_CACHE || false)
-  -h, --help                                   display help for command
-
-Commands:
-  run                                          Runs bot normally
-  check [options] <activityIdentifier> [type]  Run check(s) on a specific activity
-  help [command]                               display help for command
-
-```
-
-### Logging
-
-### 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](https://www.reddit.com/prefs/apps) 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.
+![Oauth View](docs/screenshots/oauth.jpg)
 
 ## License
 

app.json

@@ -1,7 +1,7 @@
 {
   "name": "Reddit Context Bot",
   "description": "An event-based, reddit moderation bot built on top of snoowrap and written in typescript",
-  "repository": "https://github.com/FoxxMD/reddit-context-bot",
+  "repository": "https://github.com/FoxxMD/context-mod",
   "stack": "container",
   "env": {
     "CLIENT_ID": {

docs/README.md

@@ -0,0 +1,337 @@
+# Documentation
+
+# Table of Contents
+
+* [Getting Started](#getting-started)
+* [How It Works](#how-it-works)
+* [Concepts](#concepts)
+  * [Check](#checks)
+  * [Rule](#rule)
+    * [Examples](#available-rules)
+  * [Rule Set](#rule-set)
+    * [Examples](#rule-set-examples)
+  * [Action](#action)
+    * [Examples](#available-actions)
+  * [Filters](#filters)
+* [Configuration and Usage](#configuration-and-usage)
+* [Common Resources](#common-resources)
+  * [Activities `window`](#activities-window)
+  * [Comparisons](#thresholds-and-comparisons)
+  * [Activity Templating](/docs/actionTemplating.md)
+* [Best Practices](#best-practices)
+  * [Named Rules](#named-rules)
+  * [Rule Order](#rule-order)
+  * [Caching](#caching)
+* FAQ
+
+## Getting Started
+
+Review **at least** the **How It Works** and **Concepts** below, then:
+
+* For **Operators** (running a bot instance) refer to [**Operator Getting Started**](/docs/gettingStartedOperator.md)  guide
+* For **Moderators** (configuring an existing bot for your subreddit) refer to the [**Moderator Getting Started**](/docs/gettingStartedMod.md) guide
+
+## How It Works
+
+Where possible Context Mod (CM) uses the same terminology as, and emulates the behavior, of **automoderator** so if you are familiar with that much of this may seem familiar to you.
+
+CM's lifecycle looks like this:
+
+#### 1) A new event in your subreddit is received by CM
+
+The events CM watches for are configured by you. These can be new modqueue/unmoderated items, submissions, or comments.
+
+#### 2) CM sequentially processes each Check in your configuration
+
+A **Check** is a set of:
+
+* One or more **Rules** that define what conditions should **trigger** this Check
+* One or more **Actions** that define what the bot should do once the Check is **triggered**
+
+#### 3) Each Check is processed, *in order*, until a Check is triggered
+
+Once a Check is **triggered** no more Checks will be processed. This means all subsequent Checks in your configuration (in the order you listed them) are basically skipped.
+
+#### 4) All Actions from that Check are executed
+
+After all Actions are executed CM returns to waiting for the next Event.
+
+## Concepts
+
+Core, high-level concepts regarding how CM works.
+
+### Checks
+
+A **Check** is the main logical unit of behavior for the bot. It is equivalent to "if X then Y". A Check is comprised of:
+
+* One or more **Rules** that are tested against an **Activity**
+* One of more **Actions** that are performed when the **Rules** are satisfied
+
+The bot's configuration can be made up of one or more **Checks** that are processed **in the order they are listed in the configuration.**
+
+Once a Check is **triggered** (its Rules are satisfied and Actions performed) all subsequent Checks are skipped.
+
+Some other important concepts regarding Checks:
+
+* All Checks have a **kind** (defined in the configuration) that determine if they should run on **Submissions** or **Comments**
+* Checks have a **condition** property that determines when they are considered **triggered**
+  * If the **condition** is `AND` then ALL of their **Rules** must be **triggered** for the Check to be **triggered**
+  * If the **condition** is `OR` then if ANY **Rules** is triggered **triggered** then the Check is **triggered**
+
+Examples of different types of Checks can be found in the [subreddit-ready examples.](/docs/examples/subredditReady)
+  
+### Rule
+
+A **Rule** is some set of **criteria** (conditions) that are tested against an Activity (comment/submission), a User, or a User's history. A Rule is considered **triggered** when the **criteria** for that rule are found to be **true** for whatever is being tested against.
+
+There are generally three main properties for a Rule:
+
+* **Critiera** -- The conditions/values you want to test for.
+* **Activities Window** -- If applicable, the range of activities that the **criteria** will be tested against.
+* **Rule-specific options** -- Any number of options that modify how the **criteria** are tested.
+
+CM has different **Rules** that can test against different types of behavior and aspects of a User, their history, and the Activity (submission/common) being checked.
+
+#### Available Rules
+Find detailed descriptions of all the Rules, with examples, below:
+
+* [Attribution](/docs/examples/attribution)
+* [Recent Activity](/docs/examples/recentActivity)
+* [Repeat Activity](/docs/examples/repeatActivity)
+* [History](/docs/examples/history)
+* [Author](/docs/examples/author)
+* Regex
+
+### Rule Set
+
+A **Rule Set** is a "grouped" set of `Rules` with a **trigger condition** specified. 
+
+Rule Sets can be used interchangeably with other **Rules** and **Rule Sets** in the `rules` list of a **Check**. 
+
+They allow you to create more complex trigger behavior by combining multiple rules into one "parent rule".
+
+It consists of:
+
+* **condition** -- Under what condition should the Rule Set be considered triggered?
+  * `AND` -- ALL Rules in the Rule Set must **trigger** in order for the Rule Set to **trigger.**
+  * `OR` -- ANY Rule in the Rule Set that is **triggered** will trigger the whole Rule Set.
+* **rules** -- The **Rules** for the Rule Set.
+
+Example
+```json5
+{
+  "condition": "AND",
+  "rules": [
+    // all the rules go here
+  ]
+}
+```
+#### Rule Set Examples
+
+* [**Detailed Example**](/docs/examples/advancedConcepts/ruleSets.json5)
+
+### Action
+
+An **Action** is some action the bot can take against the checked Activity (comment/submission) or Author of the Activity. CM has Actions for most things a normal reddit user or moderator can do.
+
+#### Available Actions
+
+* Remove (Comment/Submission)
+* Flair (Submission)
+* Ban (User)
+* Approve (Comment/Submission)
+* Comment (Reply to Comment/Submission)
+* Lock (Comment/Submission)
+* Report (Comment/Submission)
+* [UserNote](/docs/examples/userNotes) (User, when /r/Toolbox is used)
+
+For detailed explanation and options of what individual Actions can do [see the links in the `actions` property in the schema.](https://json-schema.app/view/%23/%23%2Fdefinitions%2FSubmissionCheckJson?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json)
+
+### Filters
+
+**Checks, Rules, and Actions** all have two additional (optional) criteria "tests". These tests behave differently than rule/check triggers in that:
+
+* When they **pass** the thing being tested continues to process as usual
+* When they **fail** the thing being tested **is skipped, not failed.**
+
+For **Checks** and **Actions** skipping means that the thing is not processed. The Action is not run, the Check is not triggered.
+
+In the context of **Rules** (in a Check) skipping means the Rule does not get run BUT it does not fail. The Check will continue processing as if the Rule did not exist. However, if ALL Rules in a Check are skipped then the Check does "fail" (is not triggered).
+
+#### Available Filters
+
+##### Item Filter (`itemIs`)
+
+This filter will test against the **state of the Activity currently being run.** Some criteria available to test against IE "Is the activity...":
+
+* removed
+* nsfw
+* locked
+* stickied
+* deleted
+* etc...
+
+The `itemIs` filter is made up of an array (list) of `State` criteria objects. **All** criteria in the array must pass for this filter to pass.
+
+There are two different State criteria depending on what type of Activity is being tested:
+
+* Submission -- [SubmissionState](https://json-schema.app/view/%23/%23%2Fdefinitions%2FSubmissionCheckJson/%23%2Fdefinitions%2FSubmissionState?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json)
+* Comment -- [CommentState](https://json-schema.app/view/%23/%23%2Fdefinitions%2FCommentCheckJson/%23%2Fdefinitions%2FCommentState?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json)
+
+##### Author Filter (`authorIs`)
+
+This filter will test against the **Author of the Activity currently being run.** Some criteria available to test against:
+
+* account age
+* comment, link, and total karma
+* subreddit flair text/css
+* name
+* User Notes
+* verified
+* etc...
+
+The `authorIs` filter is made up two (optional) lists of [`AuthorCriteria`](https://json-schema.app/view/%23/%23%2Fdefinitions%2FSubmissionCheckJson/%23%2Fdefinitions%2FAuthorOptions/%23%2Fdefinitions%2FAuthorCriteria?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json) criteria objects that define how the test behaves:
+
+* `include` list -- If **any** `AuthorCriteria` from this list passes then the `authorIs` test passes
+* `exclude` list -- If **any** `AuthorCriteria` from this list **does not pass** then the `authorIs` test passes. **Note:** This property is ignored if `include` is also present IE you cannot use both properties at the same time.
+
+Refer to the [app schema for `AuthorCriteria`](https://json-schema.app/view/%23/%23%2Fdefinitions%2FSubmissionCheckJson/%23%2Fdefinitions%2FAuthorOptions/%23%2Fdefinitions%2FAuthorCriteria?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json) for all available properties to test against.
+
+Some examples of using `authorIs` can be found in the [Author examples.](/docs/examples/author)
+
+## Configuration And Usage
+
+* For **Operator/Bot maintainers** see **[Operation Configuration](/docs/operatorConfiguration.md)**
+  * [CLI Usage](docs/operatorConfiguration.md#cli-usage)
+* For **Moderators** 
+  * Refer to the [examples folder](/docs/examples) or the [subreddit-ready examples](/docs/examples/subredditReady)
+  * as well as the [schema editor](https://json-schema.app/view/%23?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json) which has
+    * fully annotated configuration data/structure
+    * generated examples in json/yaml
+    * built-in editor that automatically validates your config
+
+## Common Resources
+
+Technical information on recurring, common data/patterns used in CM.
+
+### Activities `window`
+
+Most **Rules** must define the **range of Activities (submissions and/or comments)** that will be used to check the criteria of the Rule. This range is defined wherever you see a `window` property in configuration.
+
+Refer to the [Activities Window](/docs/activitiesWindow.md) documentation for a technical explanation with examples.
+
+### Thresholds and Comparisons
+
+Most rules/filters have criteria that require you to define a specific condition to test against. This can be anything from repeats of activities to account age.
+
+In all of these scenarios the condition is defined using a subset of [comparison operators](https://www.codecademy.com/articles/fwd-js-comparison-logical) (very similar to how automoderator does things).
+
+Available operators:
+
+* `<` -- **less than** => `5 < 6` => 5 is less than 6
+* `>` -- **greater than** => `6 > 5` => 6 is greater than 5
+* `<=` -- **less than or equal to** => `5 <= 5` => 5 is less than **or equal to** 5
+* `>=` -- **greater than or equal to** => `5 >= 5` => 5 is greater than **or equal to** 5
+
+In the context of a rule/filter comparison you provide the comparison **omitting** the value that is being tested. An example...
+
+The RepeatActivity rule has a `threshold` comparison to test against the number of repeat activities it finds
+
+* You want the rule to trigger if it finds **4 or more repeat activities**
+* The rule would be configured like this `"threshold": ">= 4"`
+
+Essentially what this is telling the rule is `threshold: "x >= 4"` where `x` is the largest repeat of activities it finds.
+
+#### Other Comparison Types
+
+Other than comparison numeric values there are two other values that can be compared (depending on the criteria)
+
+##### Percentages
+
+Some criteria accept an optional **percentage** to compare against:
+
+```
+"threshold": "> 20%"
+```
+
+Refer to the individual rule/criteria schema to see what this percentage is comparing against.
+
+##### Durations
+
+Some criteria accept an optional **duration** to compare against:
+
+```
+"threshold": "< 1 month"
+```
+
+The duration value compares a time range from **now** to `duration value` time in the past.
+
+Refer to [duration values in activity window documentation](/docs/activitiesWindow.md#duration-values) as well as the individual rule/criteria schema to see what this duration is comparing against.
+
+## Best Practices
+
+### Named Rules
+
+All **Rules** in a subreddit's configuration can be assigned a **name** that can then be referenced from any other Check. 
+
+Create general-use rules so they can be reused and de-clutter your configuration. Additionally, CM will automatically cache the result of a rule so there is a performance and api usage benefit to re-using Rules.
+
+See [ruleNameReuse.json5](/docs/examples/advancedConcepts/ruleNameReuse.json5) for a detailed configuration with annotations.
+
+### Check Order
+
+Checks are run in the order they appear in your configuration, therefore you should place your highest requirement/severe action checks at the top and lowest requirement/moderate actions at the bottom.
+
+This is so that if an Activity warrants a more serious reaction that Check is triggered first rather than having a lower requirement check with less severe actions triggered and causing all subsequent Checks to be skipped.
+
+* Attribution >50% AND Repeat Activity 8x AND Recent Activity in 2 subs => remove submission + ban
+* Attribution >20% AND Repeat Activity 4x AND Recent Activity in 5 subs => remove submission + flair user restricted
+* Attribution >20% AND Repeat Activity 2x => remove submission
+* Attribution >20% AND History comments <30% => remove submission
+* Attribution >15% => report
+* Repeat Activity 2x => report
+* Recent Activity in 3 subs => report
+* Author not vetted => flair new user submission
+
+### Rule Order
+
+The ordering of your Rules within a Check/RuleSet can have an impact on Check performance (speed) as well as API usage.
+
+Consider these three rules:
+
+* Rule A -- Recent Activity => 3 subreddits => last 15 submissions
+* Rule B -- Repeat Activity => last 3 days
+* Rule C -- Attribution => >10% => last 90 days or 300 submissions
+
+The first two rules are lightweight in their requirements -- Rule A can be completed in 1 API call, Rule B potentially completed in 1 Api call.
+
+However, depending on how active the Author is, Rule C will take *at least* 3 API calls just to get all activities (Reddit limit 100 items per call).
+
+If the Check is using `AND` condition for its rules (default) then if either Rule A or Rule B fail then Rule C will never run. This means 3 API calls never made plus the time waiting for each to return.
+
+**It is therefore advantageous to list your lightweight Rules first in each Check.**
+
+### Caching
+
+ContextMod implements caching functionality for:
+
+* author history (`window` criteria in rules)
+* `authorIs` results
+* `content` that uses wiki pages (on Comment/Report/Ban Actions)
+* and User Notes
+
+All of these use api requests so caching them reduces api usage.
+
+Cached results can be re-used if the criteria in configuration is identical to a previously cached result. So...
+
+* author history cache results are re-used if **`window` criteria on a Rule is identical to the `window` on another Rule** IE always use **7 Days** or always use **50 Items** for absolute counts.
+* `authorIs` criteria is identical to another `authorIs` elsewhere in configuration..
+* etc...
+
+Re-use will result in less API calls and faster Check times.
+
+PROTIP: You can monitor the re-use of cache in the `Cache` section of your subreddit on the web interface. See the tooltips in that section for a better breakdown of cache statistics.
+
+## FAQ
+
+TODO

docs/actionTemplating.md

@@ -0,0 +1,72 @@
+Actions that can submit text (Report, Comment) will have their `content` values run through a [Mustache Template](https://mustache.github.io/). This means you can insert data generated by Rules into your text before the Action is performed.
+
+See here for a [cheatsheet](https://gist.github.com/FoxxMD/d365707cf99fdb526a504b8b833a5b78) and [here](https://www.tsmean.com/articles/mustache/the-ultimate-mustache-tutorial/) for a more thorough tutorial.
+
+All Actions with `content` have access to this data:
+
+```json5
+
+{
+    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,
+        botLink: 'string' // a link to the bot's FAQ
+    },
+    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": "repeatActivity",
+  }
+]
+
+```
+
+**To see what data is available for individual Rules [consult the schema](#configuration) 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."
+
+```

docs/activitiesWindow.md

@@ -0,0 +1,217 @@
+# Activity Window
+
+Most **Rules** have a `window` property somewhere within their configuration. This property defines the range of **Activities** (submission and/or comments) that should be retrieved for checking the criteria of the Rule.
+
+As an example if you want to run an **Recent Activity Rule** to check if a user has had activity in /r/mealtimevideos you also need to define what range of activities you want to look at from that user's history.
+
+## `window` property overview (tldr)
+
+The value of `window` can be any of these types:
+
+* `number` count of activities
+* `string` [duration](#duration-string-recommended) or [iso 8601](#an-iso-8601-duration-string)
+* [duration `object`](#duration-object)
+* [ActivityWindowCriteria `object`](#activitywindowcriteria)
+
+Examples of all of the above
+
+<details>
+
+```
+// count, last 100 activities
+{
+  "window": 100
+}
+
+// duration string, last 10 days
+{
+  "window": "10 days"
+}
+
+// duration object, last 2 months and 5 days
+{
+  "window": {
+    "months": 2,
+    "days": 5,
+  }
+}
+
+// iso 8601 string, last 15 minutes
+{
+  "window": "PT15M"
+}
+
+// ActivityWindowCriteria, last 100 activities or 6 weeks of activities (whichever is found first)
+{
+  "window": {
+    "count": 100,
+    "duration": "6 weeks"
+  }
+}
+```
+</details>
+
+## Types of Ranges
+
+There are two types of values that can be used when defining a range:
+
+### Count
+
+This is the **number** of activities you want to retrieve. It's straightforward -- if you want to look at the last 100 activities for a user you can use `100` as the value.
+
+### Duration
+
+A **duration of time** between which all activities will be retrieved. This is a **relative value** that calculates the actual range based on **the duration of time subtracted from when the rule is run.**
+
+For example:
+
+* Today is **July 15th**
+* You define a duration of **10 days**
+
+Then the range of activities to be retrieved will be between **July 5th and July 15th** (10 days).
+
+#### Duration Values
+
+The value used to define the duration can be **any of these three types**:
+
+##### Duration String (recommended)
+
+A string consisting of
+
+* A [Dayjs unit of time](https://day.js.org/docs/en/durations/creating#list-of-all-available-units)
+* The value of that unit of time
+
+Examples:
+
+* `9 days`
+* `14 hours`
+* `80 seconds`
+
+You can ensure your string is valid by testing it [here.](https://regexr.com/61em3)
+
+##### Duration Object
+
+If you need to specify multiple units of time for your duration you can instead provide a [Dayjs duration **object**](https://day.js.org/docs/en/durations/creating#list-of-all-available-units) consisting of Dayjs unit-values.
+
+Example
+
+```json
+{
+  "days": 4,
+  "hours": 6,
+  "minutes": 20
+}
+```
+
+##### An ISO 8601 duration string
+
+If you're a real nerd you can also use a [standard duration](https://en.wikipedia.org/wiki/ISO_8601#Durations)) string.
+
+Examples
+
+* `PT15M` (15 minutes)
+
+Ensure your string is valid by testing it [here.](https://regexr.com/61em9)
+
+## ActivityWindowCriteria
+
+This is an object that lets you specify more granular conditions for your range.
+
+The full object looks like this:
+
+```json
+{
+  "count": 100,
+  "duration": "10 days",
+  "satisfyOn": "any",
+  "subreddits": {
+    "include": ["mealtimevideos","pooptimevideos"],
+    "exclude": ["videos"]
+  }
+}
+```
+
+### Specifying Range
+
+You may use **one or both range properties.**
+
+If both range properties are specified then the value `satisfyOn` determines how the final range is determined
+
+
+#### Using `"satisfyOn": "any"` (default)
+
+If **any** then Activities will be retrieved until one of the range properties is met, **whichever occurs first.**
+
+Example 
+```json
+{
+  "count": 80,
+  "duration": "90 days",
+  "satisfyOn": "any"
+}
+```
+Activities are retrieved in chunks of 100 (or `count`, whichever is smaller)
+
+* If 90 days of activities returns only 40 activities => returns 40 activities
+* If 80 activities is only 20 days of range => 80 activities
+
+#### Using `"satisfyOn": "all"`
+
+If **all** then both ranges must be satisfied. Effectively, whichever range produces the most Activities will be the one that is used.
+
+Example
+```json
+{
+  "count": 100,
+  "duration": "90 days",
+  "satisfyOn": "all"
+}
+```
+Activities are retrieved in chunks of 100 (or `count`, whichever is smaller)
+
+* If at 90 days of activities => 40 activities retrieved
+  * continue retrieving results until 100 activities
+  * so range is >90 days of activities
+* If at 100 activities => 20 days of activities retrieved
+  * continue retrieving results until 90 days of range
+  * so results in >100 activities
+
+### Filtering Activities
+
+You may filter retrieved Activities using an array of subreddits.
+
+**Note:** Activities are filtered **before** range check is made so you will always end up with specified range (but may require more api calls if many activities are filtered out)
+
+#### Include
+
+Use **include** to specify which subreddits should be included from results
+
+Example where only activities from /r/mealtimevideos and /r/modsupport will be returned
+```json
+{
+  "count": 100,
+  "duration": "90 days",
+  "satisfyOn": "any",
+  "subreddits": {
+    "include": ["mealtimevideos","modsupport"]
+  }
+}
+
+```
+
+#### Exclude
+
+Use **exclude** to specify which subreddits should NOT be in the results
+
+Example where activities from /r/mealtimevideos and /r/modsupport will not be returned in results
+```json
+{
+  "count": 100,
+  "duration": "90 days",
+  "satisfyOn": "any",
+  "subreddits": {
+    "exclude": ["mealtimevideos","modsupport"]
+  }
+}
+```
+**Note:** `exclude` will be ignored if `include` is also present.

docs/botAuthentication.md

@@ -0,0 +1,94 @@
+**Note:** This is for **bot operators.** If you are a subreddit moderator check out the **[Getting Started Guide](/docs/gettingStartedMod.md)**
+
+Before you can start using your bot on reddit there are a few steps you must take:
+
+* Create your bot account IE the reddit account that will be the "bot"
+* Create a Reddit application
+* Authenticate your bot account with the application
+
+At the end of this process you will have this info:
+
+* clientId
+* clientSecret
+* refreshToken
+* accessToken
+
+**Note:** If you already have this information you can skip this guide **but make sure your redirect uri is correct if you plan on using the web interface.**
+
+# Table Of Contents
+
+* [Creating an Application](#create-application)
+* [Authenticate Your Bot](#authenticate-your-bot-account)
+  * [Using CM OAuth Helper](#cm-oauth-helper-recommended)
+  * [Using Aardvark OAuth Helper](#aardvark-oauth-helper)
+* [Provide Credentials to CM](#provide-credentials-to-cm)
+
+# Create Application
+
+Visit [your reddit preferences](https://www.reddit.com/prefs/apps) and at the bottom of the page go through the **create an(other) app** process.
+* Give it a **name**
+* Choose **web app**
+* If you know what you will use for **redirect uri** go ahead and use it, otherwise use **http://localhost:8085** for now
+
+Click **create app**.
+
+Then write down your **Client ID, Client Secret, and redirect uri** somewhere (or keep this webpage open)
+
+# Authenticate Your Bot Account
+
+There are **two ways** you can authenticate your bot account. It is recommended to use the CM oauth helper.
+
+## CM OAuth Helper (Recommended)
+
+This method will use CM's built in oauth flow. It is recommended because it will ensure your bot is authenticated with the correct oauth permissions.
+
+### Start CM with Client ID/Secret
+
+Start the application while providing the **Client ID** and **Client Secret** you received. Refer to the [operator config guide](/docs/operatorConfiguration.md) if you need help with this.
+
+Examples:
+
+* CLI - `node src/index.js --clientId=myId --clientSecret=mySecret`
+* Docker - `docker run -e "CLIENT_ID=myId" -e "CLIENT_SECRET=mySecret" foxxmd/context-mod`
+
+Then open the CM web interface (default is [http://localhost:8085](http://localhost:8085))
+
+Follow the directions in the helper to finish authenticating your bot and get your credentials (Access Token and Refresh Token)
+
+## Aardvark OAuth Helper
+
+This method should only be used if you cannot use the [CM OAuth Helper method](#cm-oauth-helper-recommended) because you cannot access the CM web interface.
+
+* Visit [https://not-an-aardvark.github.io/reddit-oauth-helper/](https://not-an-aardvark.github.io/reddit-oauth-helper/) and follow the instructions given.  
+  * **Note:** You will need to update your **redirect uri.**
+* 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 CM may not work correctly**
+    * edit
+    * flair
+    * history
+    * identity
+    * modcontributors
+    * modflair
+    * modposts
+    * modself
+    * mysubreddits
+    * read
+    * report
+    * submit
+    * wikiread
+    * wikiedit (if you are using Toolbox User Notes)
+* 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. Save these to use with CM.
+
+# Provide Credentials to CM
+
+At the end of the last step you chose you should now have this information saved somewhere:
+
+* clientId
+* clientSecret
+* refreshToken
+* accessToken
+
+This is all the information you need to run your bot with CM.
+
+Using these credentials follow the [operator config guide](/docs/operatorConfiguration.md) to finish setting up your CM instance.

docs/examples/README.md

@@ -0,0 +1,26 @@
+# Examples
+
+This directory contains example of valid, ready-to-go configurations for Context Mod for the purpose of:
+
+* showcasing what the bot can do
+* providing best practices for writing your configuration
+* providing generally useful configurations **that can be used immediately** or as a jumping-off point for your configuration
+
+
+    
+### Examples Overview
+
+* Rules
+  * [Attribution](/docs/examples/attribution)
+  * [Recent Activity](/docs/examples/recentActivity)
+  * [Repeat Activity](/docs/examples/repeatActivity)
+  * [History](/docs/examples/history)
+  * [Author](/docs/examples/author)
+* [Toolbox User Notes](/docs/examples/userNotes)
+* [Advanced Concepts](/docs/examples/advancedConcepts)
+  * [Rule Sets](/docs/examples/advancedConcepts/ruleSets.json5)
+  * [Name Rules](/docs/examples/advancedConcepts/ruleNameReuse.json5)
+  * [Check Ordering](/docs/examples/advancedConcepts)
+* [Subreddit-ready examples](/docs/examples/subredditReady)
+
+PROTIP: You can edit/build on examples by using the [schema editor.](https://json-schema.app/view/%23?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json)

docs/examples/advancedConcepts/README.md

@@ -1,6 +1,6 @@
 ### Named Rules
 
-See [ruleNameReuse.json5](/examples/advancedConcepts/ruleNameReuse.json5)
+See [ruleNameReuse.json5](/docs/examples/advancedConcepts/ruleNameReuse.json5)
 
 ### Check Order
 
@@ -23,7 +23,7 @@ The `rules` array on a `Checks` can contain both `Rule` objects and `RuleSet` ob
 
 A **Rule Set** is a "nested" set of `Rule` objects with a passing condition specified. These allow you to create more complex trigger behavior by combining multiple rules. 
 
-See **[ruleSets.json5](/examples/advancedConcepts/ruleSets.json5)** for a complete example as well as consulting the [schema](https://json-schema.app/view/%23%2Fdefinitions%2FRuleSetJson?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Freddit-context-bot%2Fmaster%2Fsrc%2FSchema%2FApp.json).
+See **[ruleSets.json5](/docs/examples/advancedConcepts/ruleSets.json5)** for a complete example as well as consulting the [schema](https://json-schema.app/view/%23%2Fdefinitions%2FRuleSetJson?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json).
 
 ### Rule Order
 
@@ -45,7 +45,7 @@ If the Check is using `AND` condition for its rules (default) then if either Rul
 
 ### API Caching
 
-Context bot implements some basic caching functionality for **Author Activities** and wiki pages (on Comment/Report Actions).
+Context Mod implements some basic caching functionality for **Author Activities** and wiki pages (on Comment/Report Actions).
 
 **Author Activities** are cached for a subreddit-configurable amount of time (10 seconds by default). A cached activities set can be re-used if the **window on a Rule is identical to the window on another Rule**.
 

docs/examples/advancedConcepts/ruleNameReuse.json5

@@ -14,13 +14,11 @@
           "kind": "attribution",
           "criteria": [
             {
-              "threshold": "10%",
-              "window": {
-                "days": 90
-              }
+              "threshold": "> 10%",
+              "window": "90 days"
             },
             {
-              "threshold": "10%",
+              "threshold": "> 10%",
               "window": 100
             }
           ],
@@ -54,7 +52,7 @@
           "useSubmissionAsReference":true,
           "thresholds": [
             {
-              "totalCount": 1,
+              "threshold": ">= 1",
               "subreddits": [
                 "DeFreeKarma",
                 "FreeKarma4U",
@@ -63,9 +61,7 @@
               ]
             }
           ],
-          "window": {
-            "days": 7
-          }
+          "window": "7 days"
         }
       ],
       "actions": [

docs/examples/advancedConcepts/ruleSets.json5

@@ -13,13 +13,11 @@
           "kind": "attribution",
           "criteria": [
             {
-              "threshold": "10%",
-              "window": {
-                "days": 90
-              }
+              "threshold": "> 10%",
+              "window": "90 days"
             },
             {
-              "threshold": "10%",
+              "threshold": "> 10%",
               "window": 100
             }
           ],
@@ -42,14 +40,12 @@
               "kind": "attribution",
               "criteria": [
                 {
-                  "threshold": "10%",
+                  "threshold": "> 10%",
                   "thresholdOn": "submissions",
-                  "window": {
-                    "days": 90
-                  }
+                  "window": "90 days"
                 },
                 {
-                  "threshold": "10%",
+                  "threshold": "> 10%",
                   "thresholdOn": "submissions",
                   "window": 100
                 }
@@ -62,23 +58,12 @@
               "criteriaJoin": "OR",
               "criteria": [
                 {
-                  "window": {
-                    "days": 90
-                  },
-                  "comment": {
-                    "threshold": "50%",
-                    "condition": "<"
-                  }
+                  "window": "90 days",
+                  "comment": "< 50%"
                 },
                 {
-                  "window": {
-                    "days": 90
-                  },
-                  "comment": {
-                    "asOp": true,
-                    "threshold": "40%",
-                    "condition": ">"
-                  }
+                  "window": "90 days",
+                  "comment": "> 40% OP"
                 }
               ]
             }
@@ -95,5 +80,5 @@
         }
       ]
     },
-  ]
+  ],
 }

docs/examples/attribution/README.md

@@ -6,9 +6,9 @@ The **Attribution** rule will aggregate an Author's content Attribution (youtube
 * Look at all domains or only media (youtube, vimeo, etc.)
 * Include self posts (by reddit domain) or not
 
-Consult the [schema](https://json-schema.app/view/%23/%23%2Fdefinitions%2FCheckJson/%23%2Fdefinitions%2FAttributionJSONConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Freddit-context-bot%2Fmaster%2Fsrc%2FSchema%2FApp.json) for a complete reference of the rule's properties.
+Consult the [schema](https://json-schema.app/view/%23/%23%2Fdefinitions%2FCheckJson/%23%2Fdefinitions%2FAttributionJSONConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json) for a complete reference of the rule's properties.
 
 ### Examples
 
-* [Self Promotion as percentage of all Activities](/examples/attribution/redditSelfPromoAll.json5) - Check if Author is submitting much more than they comment.
-* [Self Promotion as percentage of Submissions](/examples/attribution/redditSelfPromoSubmissionsOnly.json5) - Check if any of Author's aggregated submission origins are >10% of their submissions
+* [Self Promotion as percentage of all Activities](/docs/examples/attribution/redditSelfPromoAll.json5) - Check if Author is submitting much more than they comment.
+* [Self Promotion as percentage of Submissions](/docs/examplesm/attribution/redditSelfPromoSubmissionsOnly.json5) - Check if any of Author's aggregated submission origins are >10% of their submissions

docs/examples/attribution/redditSelfPromoAll.json5

@@ -13,17 +13,15 @@
           "criteria": [
             {
               // threshold can be a percent or an absolute number
-              "threshold": "10%",
+              "threshold": "> 10%",
               // The default is "all" -- calculate percentage of entire history (submissions & comments)
               // "thresholdOn": "all",
 
               // look at last 90 days of Author's activities (comments and submissions)
-              "window": {
-                "days": 90
-              }
+              "window": "90 days"
             },
             {
-              "threshold": "10%",
+              "threshold": "> 10%",
               // look at Author's last 100 activities (comments and submissions)
               "window": 100
             }

docs/examples/attribution/redditSelfPromoSubmissionsOnly.json5

@@ -13,17 +13,15 @@
           "criteria": [
             {
               // threshold can be a percent or an absolute number
-              "threshold": "10%",
+              "threshold": "> 10%",
               // calculate percentage of submissions, rather than entire history (submissions & comments)
               "thresholdOn": "submissions",
 
               // look at last 90 days of Author's activities (comments and submissions)
-              "window": {
-                "days": 90
-              }
+              "window": "90 days"
             },
             {
-              "threshold": "10%",
+              "threshold": "> 10%",
               "thresholdOn": "submissions",
               // look at Author's last 100 activities (comments and submissions)
               "window": 100

docs/examples/author/README.md

@@ -0,0 +1,38 @@
+# Author
+
+## Rule
+
+The **Author** rule triggers if any [AuthorCriteria](https://json-schema.app/view/%23%2Fdefinitions%2FAuthorCriteria?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json) from a list are either **included** or **excluded**, depending on which property you put them in.
+
+**AuthorCriteria** that can be checked:
+* name (u/userName)
+* author's subreddit flair text
+* author's subreddit flair css
+* author's subreddit mod status
+* [Toolbox User Notes](/docs/examples/userNotes)
+
+The Author **Rule** is best used in conjunction with other Rules to short-circuit a Check based on who the Author is. It is easier to use a Rule to do this then to write **author filters** for every Rule (and makes Rules more re-useable).
+
+Consult the [schema](https://json-schema.app/view/%23%2Fdefinitions%2FAuthorRuleJSONConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json) for a complete reference of the rule's properties.
+
+### Examples
+
+* Basic examples
+    * [Flair new user Submission](/docs/examples/author/flairNewUserSubmission.json5) - If the Author does not have the `vet` flair then flair the Submission with `New User`
+    * [Flair vetted user Submission](/docs/examples/author/flairNewUserSubmission.json5) - If the Author does have the `vet` flair then flair the Submission with `Vetted`
+* Used with other Rules
+    * [Ignore vetted user](/docs/examples/author/flairNewUserSubmission.json5) - Short-circuit the Check if the Author has the `vet` flair
+    
+## Filter
+
+All **Rules** and **Checks** have an optional `authorIs` property that takes an [AuthorOptions](https://json-schema.app/view/%23%2Fdefinitions%2FAuthorOptions?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json) object. 
+
+**This property works the same as the Author Rule except that:**
+* On **Rules** if all criteria fail the Rule is **skipped.** 
+  * If a Rule is skipped **it does not fail or pass** and so does not affect the outcome of the Check.
+  * However, if all Rules on a Check are skipped the Check will fail.
+* On **Checks** if all criteria fail the Check **fails**.
+
+### Examples
+
+* [Skip recent activity check based on author](/docs/examples/author/authorFilter.json5) - Skip a Recent Activity check for a set of subreddits if the Author of the Submission has any set of flairs.

docs/examples/author/authorFilter.json5

@@ -12,23 +12,21 @@
           "lookAt": "submissions",
           "thresholds": [
             {
-              "totalCount": 1,
+              "threshold": ">= 1",
               "subreddits": [
                 "DeFreeKarma",
                 "FreeKarma4U",
               ]
             }
           ],
-          "window": {
-            "days": 7
-          }
+          "window": "7 days"
         },
         {
           "name": "noobmemer",
           "kind": "recentActivity",
           // authors filter will be checked before a rule is run. If anything passes then the Rule is skipped -- it is not failed or triggered.
           // if *all* Rules for a Check are skipped due to authors filter then the Check will fail
-          "authors": {
+          "authorIs": {
             // each property (include/exclude) can contain multiple AuthorCriteria
             // if any AuthorCriteria passes its test the Rule is skipped
             //
@@ -51,15 +49,13 @@
           "lookAt": "submissions",
           "thresholds": [
             {
-              "totalCount": 1,
+              "threshold": ">= 1",
               "subreddits": [
                 "dankmemes",
               ]
             }
           ],
-          "window": {
-            "days": 7
-          }
+          "window": "7 days"
         }
       ],
       "actions": [

docs/examples/author/ignoreVettedUser.json5

@@ -24,13 +24,11 @@
           "kind": "attribution",
           "criteria": [
             {
-              "threshold": "10%",
-              "window": {
-                "days": 90
-              }
+              "threshold": "> 10%",
+              "window": "90 days"
             },
             {
-              "threshold": "10%",
+              "threshold": "> 10%",
               "window": 100
             }
           ],
@@ -41,16 +39,14 @@
           "lookAt": "submissions",
           "thresholds": [
             {
-              "totalCount": 1,
+              "threshold": ">= 1",
               "subreddits": [
                 "DeFreeKarma",
                 "FreeKarma4U",
               ]
             }
           ],
-          "window": {
-            "days": 7
-          }
+          "window": "7 days"
         },
         {
           "name": "memes",
@@ -58,15 +54,13 @@
           "lookAt": "submissions",
           "thresholds": [
             {
-              "totalCount": 3,
+              "threshold": ">= 3",
               "subreddits": [
                 "dankmemes",
               ]
             }
           ],
-          "window": {
-            "days": 7
-          }
+          "window": "7 days"
         }
       ],
       // will NOT run if the Author for this Submission has the flair "vet"

docs/examples/history/README.md

@@ -5,9 +5,9 @@ The **History** rule can check an Author's submission/comment statistics over a
 * Comment total or percentage of all Activity
 * Comments made as OP (commented in their own Submission) total or percentage of all Comments
 
-Consult the [schema](https://json-schema.app/view/%23%2Fdefinitions%2FHistoryJSONConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Freddit-context-bot%2Fmaster%2Fsrc%2FSchema%2FApp.json) for a complete reference of the rule's properties.
+Consult the [schema](https://json-schema.app/view/%23%2Fdefinitions%2FHistoryJSONConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json) for a complete reference of the rule's properties.
 
 ### Examples
 
-* [Low Comment Engagement](/examples/history/lowEngagement.json5) - Check if Author is submitting much more than they comment.
-* [OP Comment Engagement](/examples/history/opOnlyEngagement.json5) - Check if Author is mostly engaging only in their own content
+* [Low Comment Engagement](/docs/examples/history/lowEngagement.json5) - Check if Author is submitting much more than they comment.
+* [OP Comment Engagement](/docs/examples/history/opOnlyEngagement.json5) - Check if Author is mostly engaging only in their own content

docs/examples/history/lowEngagement.json5

@@ -12,14 +12,9 @@
           "criteria": [
             {
               // look at last 90 days of Author's activities
-              "window": {
-                "days": 90
-              },
+              "window": "90 days",
               // trigger if less than 30% of their activities in this time period are comments
-              "comment": {
-                "threshold": "30%",
-                "condition": "<"
-              }
+              "comment": "< 30%"
             },
           ]
         }

docs/examples/history/opOnlyEngagement.json5

@@ -12,15 +12,9 @@
           "criteria": [
             {
               // look at last 90 days of Author's activities
-              "window": {
-                "days": 90
-              },
-              // trigger if less than 30% of their activities in this time period are comments
-              "comment": {
-                "asOp": true,
-                "threshold": "60%",
-                "condition": ">"
-              }
+              "window": "90 days",
+              // trigger if more than 60% of their activities in this time period are comments as OP
+              "comment": "> 60% OP"
             },
           ]
         }

docs/examples/recentActivity/README.md

@@ -0,0 +1,10 @@
+# Recent Activity
+
+The **Recent Activity** rule can check if an Author has made any Submissions/Comments in a list of defined Subreddits.
+
+Consult the [schema](https://json-schema.app/view/%23%2Fdefinitions%2FRecentActivityRuleJSONConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json) for a complete reference of the rule's properties.
+
+### Examples
+
+* [Free Karma Subreddits](/docs/examples/recentActivity/freeKarma.json5) - Check if the Author has recently posted in any "free karma" subreddits
+* [Submission in Free Karma Subreddits](/docs/examples/recentActivity/freeKarmaOnSubmission.json5) - Check if the Author has posted the Submission this check is running on in any "free karma" subreddits recently

docs/examples/recentActivity/freeKarma.json5

@@ -9,13 +9,14 @@
         {
           "name": "freekarma",
           "kind": "recentActivity",
+          "useSubmissionAsReference": false,
           // when `lookAt` is not present this rule will look for submissions and comments
           // lookAt: "submissions"
           // lookAt: "comments"
           "thresholds": [
             {
               // for all subreddits, if the number of activities (sub/comment) is equal to or greater than 1 then the rule is triggered
-              "totalCount": 1,
+              "threshold": ">= 1",
               "subreddits": [
                 "DeFreeKarma",
                 "FreeKarma4U",
@@ -25,9 +26,7 @@
             }
           ],
           // will look at all of the Author's activities in the last 7 days
-          "window": {
-            "days": 7
-          }
+          "window": "7 days"
         }
       ],
       "actions": [

docs/examples/recentActivity/freeKarmaOnSubmission.json5

@@ -17,7 +17,7 @@
           "thresholds": [
             {
               // for all subreddits, if the number of activities (sub/comment) is equal to or greater than 1 then the rule is triggered
-              "totalCount": 1,
+              "threshold": ">= 1",
               "subreddits": [
                 "DeFreeKarma",
                 "FreeKarma4U",
@@ -27,9 +27,7 @@
             }
           ],
           // look at all of the Author's submissions in the last 7 days
-          "window": {
-            "days": 7
-          }
+          "window": "7 days"
         }
       ],
       "actions": [

docs/examples/repeatActivity/README.md

@@ -0,0 +1,49 @@
+# Repeat Activity
+
+The **Repeat Activity** rule will check for patterns of repetition in an Author's Submission/Comment history. Consult the [schema](https://json-schema.app/view/%23%2Fdefinitions%2FRepeatActivityJSONConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json) for a complete reference of the rule's properties.
+
+## Tuning
+
+The most critical properties for this Rule are **gapAllowance** and **lookAt**.
+
+### `lookAt`
+
+Determines which Activities from a User's history are checked when looking for repeats.
+
+Can be either:
+
+* `all` -- All of a user's submissions and comments are considered
+* `submissions` -- Only a user's submissions are considered
+
+Defaults to `all`
+
+### `gapAllowance`
+
+`gapAllowance` determines how many **non-repeat Activities** are "allowed" between "in a row" submissions. `N` number of non-repeat activities will be thrown away during the count which allows checking for patterns with a bit of "fuzziness".
+
+By default `gapAllowance: 0` so all repeats must be truly consecutive.
+___
+Consider the following example in a user's history:
+
+* crossposts 2 times
+* 1 comment
+* crossposts 2 times
+* 2 comments
+* crossposts 4 times
+
+Your goal is to remove a submission if it has been crossposted **5 times.**
+
+With defaults for lookAt and gapAllowance this rule **would not be triggered** because no set of consecutive submissions was repeated 5 times.
+
+With only `lookAt: "submissions"` this rule **would trigger** because all the comments would be ignored resulting in 8 repeats.
+
+With only `gapAllowance: 1` this rule **would not trigger** because the 2 comment non-repeat would break the "in a row" count.
+
+With only `gapAllowance: 2` this rule **would trigger** because the the 1 and 2 comment non-repeats would be thrown out resulting in 8 repeats.
+
+**Note:** `lookAt: "submissions"` should be used with caution because all comments are thrown away. This isn't indicative of real repeat behavior if the user is a heavy commenter. For this reason the default is `all`.
+
+## Examples
+
+* [Crosspost Spamming](/docs/examples/repeatActivity/crosspostSpamming.json5) - Check if an Author is spamming their Submissions across multiple subreddits
+* [Burst-posting](/docs/examples/repeatActivity/burstPosting.json5) - Check if Author is crossposting their Submissions in short bursts

docs/examples/repeatActivity/burstPosting.json5

@@ -14,11 +14,9 @@
           // the number of non-repeat activities (submissions or comments) to ignore between repeat submissions
           "gapAllowance": 3,
           // if the Author has posted this Submission 6 times, ignoring 3 non-repeat activities between each repeat, then this rule will trigger
-          "threshold": 6,
+          "threshold": ">= 6",
           // look at all of the Author's submissions in the last 7 days
-          "window": {
-            "days": 7
-          }
+          "window": "7 days"
         }
       ],
       "actions": [

docs/examples/repeatActivity/crosspostSpamming.json5

@@ -12,11 +12,9 @@
           // will only look at Submissions in Author's history that contain the same content (link) as the Submission this check was initiated by
           "useSubmissionAsReference": true,
           // if the Author has posted this Submission 5 times consecutively then this rule will trigger
-          "threshold": 5,
+          "threshold": ">= 5",
           // look at all of the Author's submissions in the last 7 days
-          "window": {
-            "days": 7
-          }
+          "window": "7 days"
         }
       ],
       "actions": [

docs/examples/subredditReady/README.md

@@ -0,0 +1,41 @@
+Provided here are **complete, ready-to-go configuration** that can copy-pasted straight into your configuration wiki page to get going with ContextMod immediately.
+
+These configurations attempt to provide sensible, non-destructive, default behavior for some common scenarios and subreddit types.
+
+In most cases these will perform decently out-of-the-box but they are not perfect. You should still monitor bot behavior to see how it performs and will most likely still need to tweak these configurations to get your desired behavior.
+
+All actions for these configurations are non-destructive in that:
+
+* All instances where an activity would be modified (remove/ban/approve) will have `dryRun: true` set to prevent the action from actually being performed
+* These instances will also have a `report` action detailing the action would have been performed
+
+**You will have to remove the `report` action and `dryRun` settings yourself.** This is to ensure that you understand the behavior the bot will be performing. If you are unsure of this you should leave them in place until you are certain the behavior the bot is performing is acceptable.
+
+## Submission-based Behavior
+
+### [Remove submissions from users who have used 'freekarma' subs to bypass karma checks](/docs/examples/subredditReady/freekarma.json5)
+
+If the user has any activity (comment/submission) in known freekarma subreddits in the past (50 activities or 6 months) then remove the submission.
+
+### [Remove submissions from users who have crossposted the same submission 4 or more times](/docs/examples/subredditReady/crosspostSpam.json5)
+
+If the user has crossposted the same submission in the past (50 activities or 6 months) 4 or more times in a row then remove the submission.
+
+### [Remove submissions from users who have crossposted or used 'freekarma' subs](/docs/examples/subredditReady/freeKarmaOrCrosspostSpam.json5)
+
+Will remove submission if either of the above two behaviors is detected
+
+### [Remove link submissions where the user's history is comprised of 10% or more of the same link](/docs/examples/subredditReady/selfPromo.json5)
+
+If the link origin (youtube author, twitter author, etc. or regular domain for non-media links)
+
+* comprises 10% or more of the users **entire** history in the past (100 activities or 6 months)
+* or comprises 10% or more of the users **submission** history in the past (100 activities or 6 months) and the user has low engagement (<50% of history is comments or 40%> of comment are as OP)
+
+then remove the submission
+
+## Comment-based behavior
+
+### [Remove comment if the user has posted the same comment 4 or more times in a row](/docs/examples/subredditReady/commentSpam.json5)
+
+If the user made the same comment (with some fuzzy matching) 4 or more times in a row in the past (50 activities or 6 months) then remove the comment.

docs/examples/subredditReady/commentSpam.json5

@@ -0,0 +1,42 @@
+{
+  "polling": ["newComm"],
+  "checks": [
+    {
+      //
+      // Stop users who spam the same comment many times
+      //
+      // Remove a COMMENT if the user has crossposted it at least 4 times in recent history
+      //
+      "name": "low xp comment spam",
+      "description": "X-posted comment >=4x",
+      "kind": "comment",
+      "condition": "AND",
+      "rules": [
+        {
+          "name": "xPostLow",
+          "kind": "repeatActivity",
+          "gapAllowance": 2,
+          "threshold": ">= 4",
+          "window": {
+            "count": 50,
+            "duration": "6 months"
+          }
+        },
+      ],
+      "actions": [
+        // remove this after confirming behavior is acceptable
+        {
+          "kind": "report",
+          "content": "Remove=> Posted same comment {{rules.xpostlow.largestRepeat}}x times"
+        },
+        //
+        //
+        {
+          "kind": "remove",
+          // remove the line below after confirming behavior is acceptable
+          "dryRun": true
+        }
+      ]
+    }
+  ]
+}

docs/examples/subredditReady/crosspostSpam.json5

@@ -0,0 +1,77 @@
+{
+  "polling": ["unmoderated"],
+  "checks": [
+    {
+      //
+      // Stop users who post low-effort, crossposted spam
+      //
+      // Remove a SUBMISSION if the user has crossposted it at least 4 times in recent history AND
+      // less than 50% of their activity is comments OR more than 40% of those comments are as OP (in the own submissions)
+      //
+      "name": "low xp spam and engagement",
+      "description": "X-posted 4x and low comment engagement",
+      "kind": "submission",
+      "itemIs": [
+        {
+          "removed": false
+        }
+      ],
+      "condition": "AND",
+      "rules": [
+        {
+          "name": "xPostLow",
+          "kind": "repeatActivity",
+          "gapAllowance": 2,
+          "threshold": ">= 4",
+          "window": {
+            "count": 50,
+            "duration": "6 months"
+          }
+        },
+        {
+          "name": "lowOrOpComm",
+          "kind": "history",
+          "criteriaJoin": "OR",
+          "criteria": [
+            {
+              "window": {
+                "count": 100,
+                "duration": "6 months"
+              },
+              "comment": "< 50%"
+            },
+            {
+              "window": {
+                "count": 100,
+                "duration": "6 months"
+              },
+              "comment": "> 40% OP"
+            }
+          ]
+        }
+      ],
+      "actions": [
+        // remove this after confirming behavior is acceptable
+        {
+          "kind": "report",
+          "content": "Remove=>{{rules.xpostlow.largestRepeat}} X-P => {{rules.loworopcomm.thresholdSummary}}"
+        },
+        //
+        //
+        {
+          "kind": "remove",
+          // remove the line below after confirming behavior is acceptable
+          "dryRun": true
+        },
+        // optionally remove "dryRun" from below if you want to leave a comment on removal
+        // PROTIP: the comment is bland, you should make it better
+       {
+          "kind": "comment",
+          "content": "Your submission has been removed because you cross-posted it {{rules.xpostlow.largestRepeat}} times and you have very low engagement outside of making submissions",
+          "distinguish": true,
+          "dryRun": true
+        }
+      ]
+    }
+  ]
+}

docs/examples/subredditReady/freeKarmaOrCrosspostSpam.json5

@@ -0,0 +1,138 @@
+{
+  "polling": [
+    "unmoderated"
+  ],
+  "checks": [
+    {
+      //
+      // Stop users who post low-effort, crossposted spam
+      //
+      // Remove a SUBMISSION if the user has crossposted it at least 4 times in recent history AND
+      // less than 50% of their activity is comments OR more than 40% of those comments are as OP (in the own submissions)
+      //
+      "name": "remove on low xp spam and engagement",
+      "description": "X-posted 4x and low comment engagement",
+      "kind": "submission",
+      "itemIs": [
+        {
+          "removed": false
+        }
+      ],
+      "condition": "AND",
+      "rules": [
+        {
+          "name": "xPostLow",
+          "kind": "repeatActivity",
+          "gapAllowance": 2,
+          "threshold": ">= 4",
+          "window": {
+            "count": 50,
+            "duration": "6 months"
+          }
+        },
+        {
+          "name": "lowOrOpComm",
+          "kind": "history",
+          "criteriaJoin": "OR",
+          "criteria": [
+            {
+              "window": {
+                "count": 100,
+                "duration": "6 months"
+              },
+              "comment": "< 50%"
+            },
+            {
+              "window": {
+                "count": 100,
+                "duration": "6 months"
+              },
+              "comment": "> 40% OP"
+            }
+          ]
+        }
+      ],
+      "actions": [
+        // remove this after confirming behavior is acceptable
+        {
+          "kind": "report",
+          "content": "Remove=>{{rules.xpostlow.largestRepeat}} X-P => {{rules.loworopcomm.thresholdSummary}}"
+        },
+        //
+        //
+        {
+          "kind": "remove",
+          // remove the line below after confirming behavior is acceptable
+          "dryRun": true
+        },
+        // optionally remove "dryRun" from below if you want to leave a comment on removal
+        // PROTIP: the comment is bland, you should make it better
+        {
+          "kind": "comment",
+          "content": "Your submission has been removed because you cross-posted it {{rules.xpostlow.largestRepeat}} times and you have very low engagement outside of making submissions",
+          "distinguish": true,
+          "dryRun": true
+        }
+      ]
+    },
+    {
+      //
+      // Remove submissions from users who have recent activity in freekarma subs within the last 50 activities or 6 months (whichever is less)
+      //
+      "name": "freekarma removal",
+      "description": "Remove submission if user has used freekarma sub recently",
+      "kind": "submission",
+      "itemIs": [
+        {
+          "removed": false
+        }
+      ],
+      "condition": "AND",
+      "rules": [
+        {
+          "name": "freekarma",
+          "kind": "recentActivity",
+          "window": {
+            "count": 50,
+            "duration": "6 months"
+          },
+          "useSubmissionAsReference": false,
+          "thresholds": [
+            {
+              "subreddits": [
+                "FreeKarma4U",
+                "FreeKarma4You",
+                "KarmaStore",
+                "promote",
+                "shamelessplug",
+                "upvote"
+              ]
+            }
+          ]
+        }
+      ],
+      "actions": [
+        // remove this after confirming behavior is acceptable
+        {
+          "kind": "report",
+          "content": "Remove=> {{rules.newtube.totalCount}} activities in freekarma subs"
+        },
+        //
+        //
+        {
+          "kind": "remove",
+          // remove the line below after confirming behavior is acceptable
+          "dryRun": true
+        },
+        // optionally remove "dryRun" from below if you want to leave a comment on removal
+        // PROTIP: the comment is bland, you should make it better
+        {
+          "kind": "comment",
+          "content": "Your submission has been removed because you have recent activity in 'freekarma' subs",
+          "distinguish": true,
+          "dryRun": true
+        }
+      ]
+    }
+  ]
+}

docs/examples/subredditReady/freekarma.json5

@@ -0,0 +1,64 @@
+{
+  "polling": [
+    "unmoderated"
+  ],
+  "checks": [
+    {
+      //
+      // Remove submissions from users who have recent activity in freekarma subs within the last 50 activities or 6 months (whichever is less)
+      //
+      "name": "freekarma removal",
+      "description": "Remove submission if user has used freekarma sub recently",
+      "kind": "submission",
+      "itemIs": [
+        {
+          "removed": false
+        }
+      ],
+      "condition": "AND",
+      "rules": [
+        {
+          "name": "freekarma",
+          "kind": "recentActivity",
+          "window": {
+            "count": 50,
+            "duration": "6 months"
+          },
+          "useSubmissionAsReference": false,
+          "thresholds": [
+            {
+              "subreddits": [
+                "FreeKarma4U",
+                "FreeKarma4You",
+                "KarmaStore",
+                "upvote"
+              ]
+            }
+          ]
+        }
+      ],
+      "actions": [
+        // remove this after confirming behavior is acceptable
+        {
+          "kind": "report",
+          "content": "Remove=> {{rules.newtube.totalCount}} activities in freekarma subs"
+        },
+        //
+        //
+        {
+          "kind": "remove",
+          // remove the line below after confirming behavior is acceptable
+          "dryRun": true,
+        },
+        // optionally remove "dryRun" from below if you want to leave a comment on removal
+        // PROTIP: the comment is bland, you should make it better
+        {
+          "kind": "comment",
+          "content": "Your submission has been removed because you have recent activity in 'freekarma' subs",
+          "distinguish": true,
+          "dryRun": true,
+        }
+      ]
+    }
+  ]
+}

docs/examples/subredditReady/selfPromo.json5

@@ -0,0 +1,104 @@
+{
+  "polling": [
+    "unmoderated"
+  ],
+  "checks": [
+    {
+      //
+      // Stop users who make link submissions with a self-promotional agenda (with reddit's suggested 10% rule)
+      // https://www.reddit.com/wiki/selfpromotion#wiki_guidelines_for_self-promotion_on_reddit
+      //
+      // Remove a SUBMISSION if the link comprises more than or equal to 10% of users history (100 activities or 6 months) OR
+      //
+      // if link comprises 10% of submission history (100 activities or 6 months)
+      // AND less than 50% of their activity is comments OR more than 40% of those comments are as OP (in the own submissions)
+      //
+      "name": "Self-promo all AND low engagement",
+      "description": "Self-promo is >10% for all or just sub and low comment engagement",
+      "kind": "submission",
+      "condition": "OR",
+      "rules": [
+        {
+          "name": "attr",
+          "kind": "attribution",
+          "criteria": [
+            {
+              "threshold": ">= 10%",
+              "window": {
+                "count": 100,
+                "duration": "6 months"
+              },
+              "domains": [
+                "AGG:SELF"
+              ]
+            }
+          ],
+        },
+        {
+          "condition": "AND",
+          "rules": [
+            {
+              "name": "attrsub",
+              "kind": "attribution",
+              "criteria": [
+                {
+                  "threshold": ">= 10%",
+                  "thresholdOn": "submissions",
+                  "window": {
+                    "count": 100,
+                    "duration": "6 months"
+                  },
+                  "domains": [
+                    "AGG:SELF"
+                  ]
+                }
+              ]
+            },
+            {
+              "name": "lowOrOpComm",
+              "kind": "history",
+              "criteriaJoin": "OR",
+              "criteria": [
+                {
+                  "window": {
+                    "count": 100,
+                    "duration": "6 months"
+                  },
+                  "comment": "< 50%"
+                },
+                {
+                  "window": {
+                    "count": 100,
+                    "duration": "6 months"
+                  },
+                  "comment": "> 40% OP"
+                }
+              ]
+            }
+          ]
+        }
+      ],
+      "actions": [
+        {
+          "kind": "report",
+          "content": "{{rules.attr.largestPercent}}{{rules.attrsub.largestPercent}} of {{rules.attr.activityTotal}}{{rules.attrsub.activityTotal}} items ({{rules.attr.window}}{{rules.attrsub.window}}){{#rules.loworopcomm.thresholdSummary}} => {{rules.loworopcomm.thresholdSummary}}{{/rules.loworopcomm.thresholdSummary}}"
+        },
+        //
+        //
+        {
+          "kind": "remove",
+          // remove the line below after confirming behavior is acceptable
+          "dryRun": true
+        },
+        // optionally remove "dryRun" from below if you want to leave a comment on removal
+        // PROTIP: the comment is bland, you should make it better
+        {
+          "kind": "comment",
+          "content": "Your submission has been removed it comprises 10% or more of your recent history ({{rules.attr.largestPercent}}{{rules.attrsub.largestPercent}}). This is against [reddit's self promotional guidelines.](https://www.reddit.com/wiki/selfpromotion#wiki_guidelines_for_self-promotion_on_reddit)",
+          "distinguish": true,
+          "dryRun": true
+        }
+      ]
+    }
+  ]
+}

docs/examples/userNotes/README.md

@@ -0,0 +1,26 @@
+# [Toolbox](https://www.reddit.com/r/toolbox/wiki/docs) [User Notes](https://www.reddit.com/r/toolbox/wiki/docs/usernotes)
+
+Context Mod supports reading and writing [User Notes](https://www.reddit.com/r/toolbox/wiki/docs/usernotes) for the [Toolbox](https://www.reddit.com/r/toolbox/wiki/docs) extension.
+
+**You must have Toolbox setup for your subreddit and at least one User Note created before you can use User Notes related features on Context Bot.** 
+
+[Click here for the Toolbox Quickstart Guide](https://www.reddit.com/r/toolbox/wiki/docs/quick_start)
+
+## Filter
+
+User Notes are an additional criteria on [AuthorCriteria](https://json-schema.app/view/%23%2Fdefinitions%2FAuthorCriteria?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json) that can be used alongside other Author properties for both [filtering rules and in the AuthorRule.](/docs/examples/author/)
+
+Consult the [schema](https://json-schema.app/view/%23%2Fdefinitions%2FUserNoteCriteria?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json) for a complete reference of the **UserNoteCriteria** object that can be used in AuthorCriteria.
+
+### Examples
+
+* [Do not tag user with Good User note](/docs/examples/userNotes/usernoteFilter.json5)
+
+## Action
+
+A User Note can also be added to the Author of a Submission or Comment with the [UserNoteAction.](https://json-schema.app/view/%23%2Fdefinitions%2FUserNoteActionJson?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json)
+
+
+### Examples
+
+* [Add note on user doing self promotion](/docs/examples/userNotes/usernoteSP.json5)

docs/examples/userNotes/usernoteFilter.json5

@@ -0,0 +1,45 @@
+{
+  "checks": [
+    {
+      "name": "Self Promo Activities",
+      "description": "Tag SP only if user does not have good contributor user note",
+      // check will run on a new submission in your subreddit and look at the Author of that submission
+      "kind": "submission",
+      "rules": [
+        {
+          "name": "attr10all",
+          "kind": "attribution",
+          "author": {
+            "exclude": [
+              {
+                // the key of the usernote type to look for https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Subreddit-Wikis%3A-usernotes#working-with-note-types
+                // rule will not run if current usernote on Author is of type 'gooduser'
+                "type": "gooduser"
+              }
+            ]
+          },
+          "criteria": [
+            {
+              "threshold": "> 10%",
+              "window": "90 days"
+            },
+            {
+              "threshold": "> 10%",
+              "window": 100
+            }
+          ],
+        }
+      ],
+      "actions": [
+        {
+          "kind": "usernote",
+          // the key of usernote type
+          // https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Subreddit-Wikis%3A-usernotes#working-with-note-types
+          "type": "spamwarn",
+          // content is mustache templated as usual
+          "content": "Self Promotion: {{rules.attr10all.titlesDelim}} {{rules.attr10sub.largestPercent}}%"
+        }
+      ]
+    }
+  ]
+}

docs/examples/userNotes/usernoteSP.json5

@@ -0,0 +1,36 @@
+{
+  "checks": [
+    {
+      "name": "Self Promo Activities",
+      "description": "Check if any of Author's aggregated submission origins are >10% of entire history",
+      // check will run on a new submission in your subreddit and look at the Author of that submission
+      "kind": "submission",
+      "rules": [
+        {
+          "name": "attr10all",
+          "kind": "attribution",
+          "criteria": [
+            {
+              "threshold": "> 10%",
+              "window": "90 days"
+            },
+            {
+              "threshold": "> 10%",
+              "window": 100
+            }
+          ],
+        }
+      ],
+      "actions": [
+        {
+          "kind": "usernote",
+          // the key of usernote type
+          // https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Subreddit-Wikis%3A-usernotes#working-with-note-types
+          "type": "spamwarn",
+          // content is mustache templated as usual
+          "content": "Self Promotion: {{rules.attr10all.titlesDelim}} {{rules.attr10sub.largestPercent}}%"
+        }
+      ]
+    }
+  ]
+}

docs/gettingStartedMod.md

@@ -0,0 +1,97 @@
+This getting started guide is for **reddit moderators** -- that is, someone who wants **an existing ContextMod bot to run on their subreddit.** If you are trying to run a ContextMod
+ instance (software) please refer to the [operator getting started](/docs/gettingStartedOperator.md) guide.
+
+# Table of Contents
+
+* [Prior Knowledge](#prior-knowledge)
+* [Mod the Bot](#mod-the-bot)
+* [Creating Configuration](#configuring-the-bot)
+* [Monitor the Bot](#monitor-the-bot)
+
+# Prior Knowledge
+
+Before continuing with this guide you should first make sure you understand how a ContextMod works. Please review this documentation:
+
+* [How It Works](/docs#how-it-works)
+* [Core Concepts](/docs#concepts)
+
+# Mod The Bot
+
+First ensure that you are in communication with the **operator** for this bot. The bot **will not automatically accept a moderator invitation,** it must be manually done by the bot operator. This is an intentional barrier to ensure moderators and the operator are familiar with their respective needs and have some form of trust.
+
+Now invite the bot to moderate your subreddit. The bot should have at least these permissions:
+
+* Manage Users
+* Manage Posts and Comments
+* Manage Flair
+
+Additionally, the bot must have the **Manage Wiki Pages** permission if you plan to use [Toolbox User Notes](https://www.reddit.com/r/toolbox/wiki/docs/usernotes). If you are not planning on using this feature and do not want the bot to have this permission then you **must** ensure the bot has visibility to the configuration wiki page (detailed below).
+
+# Configuring the Bot
+
+## Setup wiki page
+
+* Visit the wiki page of the subreddit you want the bot to moderate
+  * The default location the bot checks for a configuration is at `https://old.reddit.com/r/YOURSUBERDDIT/wiki/botconfig/contextbot`
+  * If the page does not exist create it
+* Ensure the wiki page visibility is restricted
+  * On the wiki page click **settings** (**Page settings** in new reddit)
+  * Check the box for **Only mods may edit and view** and then **save**
+    * Alternatively, if you did not give the bot the **Manage Wiki Pages** permission then add it to the **allow users to edit page** setting
+
+## Procure a configuration
+
+Now you need to make the actual configuration that will be used to configure the bot's behavior on your subreddit. This may have already been done for you by your operator or you may be copying a fellow moderator's configuration.
+
+If you already have a configuration you may skip the below step and go directly to [saving your configuration](#saving-your-configuration)
+
+### Using an Example Config
+
+Visit the [Examples](https://github.com/FoxxMD/context-mod/tree/master/docs/examples) folder to find various examples of individual rules or see the [subreddit-ready examples.](/docs/examples/subredditReady)
+
+After you have found a configuration to use as a starting point:
+
+* In a new tab open the github page for the configuration you want ([example](/docs/examples/repeatActivity/crosspostSpamming.json5))
+* Click the **Raw** button, then select all and copy all of the text to your clipboard.
+
+### Build Your Own Config
+
+Additionally, you can use [this schema editor](https://json-schema.app/view/%23?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json) to build your configuration. The editor features a ton of handy features:
+
+* fully annotated configuration data/structure
+* generated examples in json/yaml
+* built-in editor that automatically validates your config
+
+PROTIP: Find an example config to use as a starting point and then build on it using the editor.
+
+## Saving Your Configuration
+
+* Open the wiki page you created in the [previous step](#setup-wiki-page) and click **edit**
+  * Copy-paste your configuration into the wiki text box
+  * Save the edited wiki page
+
+___
+
+The bot automatically checks for new configurations on your wiki page every 5 minutes. If your operator has the web interface accessible you may login there and force the config to update on your subreddit.
+
+# Monitor the Bot
+
+Monitoring the behavior of the bot is dependent on how your operator setup their instance. ContextMod comes with a built-in web interface that is secure and accessible only to moderates of subreddits it is running on. However there is some additional setup for the operator to perform in order to make this interface accessible publicly. If you do not have access to this interface please communicate with your operator.
+
+After logging in to the interface you will find your subreddit in a tab at the top of the web page. Selecting your subreddit will give you access to:
+
+* Current status of the bot
+* Current status of your configuration
+* Statistics pertaining to the number of checks/rules/actions run and cache usage
+* **A real-time view for bot logs pertaining to your subreddit**
+
+The logs are the meat and potatoes of the bot and the main source of feedback you have for fine-tuning the bot's behavior. The **verbose** log level will show you:
+
+* The event being processed
+* The individual results of triggered rules, per check
+* The checks that were run and their rules
+* The actions performed, with markdown content preview, of triggered checks
+
+This information should enable you to tweak the criteria for your rules in order to get the required behavior from the bot.
+
+Additionally, you can test your bot on any comment/submission by entering its permalink in the text bot at the top of the logs and selecting **Dry Run** -- this will run the bot on an Activity without actually performing any actions allowing you to preview the results of a run.

docs/gettingStartedOperator.md

@@ -0,0 +1,71 @@
+This getting started guide is for **Operators** -- that is, someone who wants to run the actual software for a ContentMod bot. If you are a **Moderator** check out the [moderator getting started](/docs/gettingStartedMod.md) guide instead.
+
+# Table of Contents
+
+* [Installation](#installation)
+  * [Docker](#docker-recommended)
+  * [Locally](#locally)
+  * [Heroku](#heroku-quick-deployhttpsherokucomabout)
+* [Bot Authentication](#bot-authentication)
+* [Instance Configuration](#instance-configuration)
+* [Run Your Bot and Start Moderating](#run-your-bot-and-start-moderating)
+
+# Installation
+
+In order to run a ContextMod instance you must first you must install it somewhere.
+
+ContextMod can be run on almost any operating system but it is recommended to use Docker due to ease of deployment.
+
+## Docker (Recommended)
+
+PROTIP: Using a container management tool like [Portainer.io CE](https://www.portainer.io/products/community-edition) will help with setup/configuration tremendously.
+
+### [Dockerhub](https://hub.docker.com/r/foxxmd/context-mod)
+
+```
+foxxmd/context-mod:latest
+```
+
+Adding **environmental variables** to your `docker run` command will pass them through to the app EX:
+```
+docker run -d -e "CLIENT_ID=myId" ... foxxmd/context-mod
+```
+
+### Locally
+
+Requirements:
+
+* Typescript >=4.3.5
+* Node >=15
+
+Clone this repository somewhere and then install from the working directory
+
+```bash
+git clone https://github.com/FoxxMD/context-mod.git .
+cd context-mod
+npm install
+tsc -p .
+```
+
+### [Heroku Quick Deploy](https://heroku.com/about)
+[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://dashboard.heroku.com/new?template=https://github.com/FoxxMD/context-mod)
+
+# Bot Authentication
+
+Next you need to create your bot and authenticate it with Reddit. Follow the [bot authentication guide](/docs/botAuthentication.md) to complete this step.
+
+# Instance Configuration
+
+Finally, you must provide the credentials you received from the **Bot Authentication** step to the ContextMod instance you installed earlier. Refer to the [Operator Configuration](/docs/operatorConfiguration.md) guide to learn how this can be done as there are multiple approaches depending on how you installed the software.
+
+Additionally, at this step you can also tweak many more settings and behavior concerning how your CM bot will operate.
+
+# Run Your Bot and Start Moderating
+
+Congratulations! You should now have a fully authenticated bot running on ContextMod software.
+
+In order for your Bot to operate on reddit though it **must be a moderator in the subreddit you want it to run in.** This may be your own subreddit or someone else's.
+
+**Note: ContextMod does not currently handle moderation invites automatically** and may never have this functionality. Due to the fact that many of its behaviors are api-heavy and that subreddits can control their own configuration the api and resource (cpu/memory) usage of a ContextMod instance can be highly variable. It therefore does not make sense to allow any/all subreddits to automatically have access to an instance through automatically accepting moderator invites. So...if you are planning to run a ContextMod instance for subreddits other than those you moderate you should establish solid trust with moderators of that subreddit as well as a solid line of communication in order to ensure their configurations can be tailored to best fit their needs and your resources.
+
+Once you have logged in as your bot and manually accepted the moderator invite you will need to restart your ContextMod instance in order for these changes to take effect.

docs/operatorConfiguration.md

@@ -0,0 +1,233 @@
+The **Operator** configuration refers to configuration used configure to the actual application/bot. This is different
+from the **Subreddit** configuration that is defined in each Subreddit's wiki and determines the rules/actions for
+activities the Bot runs on.
+
+# Table of Contents
+
+* [Minimum Required Configuration](#minimum-required-configuration)
+* [Defining Configuration](#defining-configuration)
+* [CLI Usage](#cli-usage)
+* [Examples](#example-configurations)
+  * [Minimum Config](#minimum-config)
+  * [Using Config Overrides](#using-config-overrides)
+* [Cache Configuration](#cache-configuration)
+
+# Minimum Required Configuration
+
+The minimum required configuration variables to run the bot on subreddits are:
+
+* clientId
+* clientSecret
+* refreshToken
+* accessToken
+
+However, only **clientId** and **clientSecret** are required to run the **oauth helper** mode in order to generate the last two
+configuration variables.
+
+Refer to the **[Bot Authentication guide](/docs/botAuthentication.md)** to retrieve the above credentials.
+
+# Defining Configuration
+
+CM can be configured using **any or all** of the approaches below. Note that **at each level ALL configuration values are
+optional** but the "required configuration" mentioned above must be available when all levels are combined.
+
+Any values defined at a **lower-listed** level of configuration will override any values from a higher-listed
+configuration.
+
+* **ENV** -- Environment variables loaded from an [`.env`](https://github.com/toddbluhm/env-cmd) file (path may be
+  specified with `--file` cli argument)
+* **ENV** -- Any already existing environment variables (exported on command line/terminal profile/etc.)
+* **FILE** -- Values specified in a JSON configuration file using the structure [in the schema](https://json-schema.app/view/%23?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FOperatorConfig.json)
+* **ARG** -- Values specified as CLI arguments to the program (see [ClI Usage](#cli-usage) below)
+
+**Note:** When reading the **schema** if the variable is available at a level of configuration other than **FILE** it will be
+noted with the same symbol as above. The value shown is the default.
+
+* To load a JSON configuration (for **FILE**) **from the command line** use the `-c` cli argument EX: `node src/index.js -c /path/to/JSON/config.json`
+* To load a JSON configuration (for **FILE**) **using an environmental variable** use `OPERATOR_CONFIG` EX: `OPERATOR_CONFIG=/path/to/JSON/config.json`
+
+[**See the Operator Config Schema here**](https://json-schema.app/view/%23?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FOperatorConfig.json)
+
+## CLI Usage
+
+Running CM from the command line is accomplished with the following command:
+
+```bash
+
+node src/index.js run
+
+```
+
+Run `node src/index.js run help` to get a list of available command line options (denoted by **ARG** above):
+
+<details>
+
+```
+Usage: index [options] [command]
+
+Options:
+  -h, --help                                   display help for command
+
+Commands:
+  run [options] [interface]                    Monitor new activities from configured subreddits.
+  check [options] <activityIdentifier> [type]  Run check(s) on a specific activity
+  unmoderated [options] <subreddits...>        Run checks on all unmoderated activity in the modqueue
+  help [command]                               display help for command
+
+
+Options:
+  -c, --operatorConfig <path>   An absolute path to a JSON file to load all parameters from (default: process.env.OPERATOR_CONFIG)
+  -i, --clientId <id>           Client ID for your Reddit application (default: process.env.CLIENT_ID)
+  -e, --clientSecret <secret>   Client Secret for your Reddit application (default: process.env.CLIENT_SECRET)
+  -a, --accessToken <token>     Access token retrieved from authenticating an account with your Reddit Application (default: process.env.ACCESS_TOKEN)
+  -r, --refreshToken <token>    Refresh token retrieved from authenticating an account with your Reddit Application (default: process.env.REFRESH_TOKEN)
+  -u, --redirectUri <uri>       Redirect URI for your Reddit application (default: process.env.REDIRECT_URI)
+  -t, --sessionSecret <secret>  Secret use to encrypt session id/data (default: process.env.SESSION_SECRET || a random string)
+  -s, --subreddits <list...>    List of subreddits to run on. Bot will run on all subs it has access to if not defined (default: process.env.SUBREDDITS)
+  -d, --logDir [dir]            Absolute path to directory to store rotated logs in. Leaving undefined disables rotating logs (default: process.env.LOG_DIR)
+  -l, --logLevel <level>        Minimum level to log at (default: process.env.LOG_LEVEL || verbose)
+  -w, --wikiConfig <path>       Relative url to contextbot wiki page EX https://reddit.com/r/subreddit/wiki/<path> (default: process.env.WIKI_CONFIG || 'botconfig/contextbot')
+  --snooDebug                   Set Snoowrap to debug. If undefined will be on if logLevel='debug' (default: process.env.SNOO_DEBUG)
+  --authorTTL <s>               Set the TTL (seconds) for the Author Activities shared cache (default: process.env.AUTHOR_TTL || 60)
+  --heartbeat <s>               Interval, in seconds, between heartbeat checks. (default: process.env.HEARTBEAT || 300)
+  --softLimit <limit>           When API limit remaining (600/10min) is lower than this subreddits will have SLOW MODE enabled (default: process.env.SOFT_LIMIT || 250)
+  --hardLimit <limit>           When API limit remaining (600/10min) is lower than this all subreddit polling will be paused until api limit reset (default: process.env.SOFT_LIMIT || 250)
+  --dryRun                      Set all subreddits in dry run mode, overriding configurations (default: process.env.DRYRUN || false)
+  --proxy <proxyEndpoint>       Proxy Snoowrap requests through this endpoint (default: process.env.PROXY)
+  --operator <name...>          Username(s) of the reddit user(s) operating this application, used for displaying OP level info/actions in UI (default: process.env.OPERATOR)
+  --operatorDisplay <name>      An optional name to display who is operating this application in the UI (default: process.env.OPERATOR_DISPLAY || Anonymous)
+  -p, --port <port>             Port for web server to listen on (default: process.env.PORT || 8085)
+  -q, --shareMod                If enabled then all subreddits using the default settings to poll "unmoderated" or "modqueue" will retrieve results from a shared request to /r/mod (default: process.env.SHARE_MOD || false)
+  -h, --help                    display help for command
+```
+
+</details>
+
+# Example Configurations
+
+## Minimum Config
+
+Below are examples of the minimum required config to run the application using all three config approaches independently.
+
+Using **FILE**
+<details>
+
+```json
+{
+  "credentials": {
+    "clientId": "f4b4df1c7b2",
+    "clientSecret": "34v5q1c56ub",
+    "refreshToken": "34_f1w1v4",
+    "accessToken": "p75_1c467b2"
+  }
+}
+```
+
+</details>
+
+Using **ENV** (`.env`)
+
+<details>
+
+```
+CLIENT_ID=f4b4df1c7b2
+CLIENT_SECRET=34v5q1c56ub
+REFRESH_TOKEN=34_f1w1v4
+ACCESS_TOKEN=p75_1c467b2
+```
+
+</details>
+
+Using **ARG**
+
+<details>
+
+```
+node src/index.js run --clientId=f4b4df1c7b2 --clientSecret=34v5q1c56ub --refreshToken=34_f1w1v4 --accessToken=p75_1c467b2
+```
+
+</details>
+
+## Using Config Overrides
+
+An example of using multiple configuration levels together IE all are provided to the application:
+
+**FILE**
+<details>
+
+```json
+{
+  "credentials": {
+    "clientId": "f4b4df1c7b2",
+    "refreshToken": "34_f1w1v4",
+    "accessToken": "p75_1c467b2"
+  }
+}
+```
+
+</details>
+
+**ENV** (`.env`)
+
+<details>
+
+```
+CLIENT_SECRET=34v5q1c56ub
+SUBREDDITS=sub1,sub2,sub3
+PORT=9008
+LOG_LEVEL=DEBUG
+```
+
+</details>
+
+**ARG**
+
+<details>
+
+```
+node src/index.js run --subreddits=sub1
+```
+
+</details>
+
+When all three are used together they produce these variables at runtime for the application:
+
+```
+clientId: f4b4df1c7b2
+clientSecret: 34v5q1c56ub
+refreshToken: 34_f1w1v4
+accessToken: accessToken
+subreddits: sub1
+port: 9008
+log level: debug
+```
+
+# Cache Configuration
+
+CM implements two caching backend **providers**. By default all providers use `memory`:
+
+* `memory` -- in-memory (non-persistent) backend
+* `redis` -- [Redis](https://redis.io/) backend
+
+Each `provider` object in configuration can be specified as:
+
+* one of the above **strings** to use the **defaults settings** or
+* an **object** with keys to override default settings
+
+A caching object in the json configuration:
+
+```json5
+{
+ "provider": {
+   "store": "memory", // one of "memory" or "redis"
+   "ttl": 60, // the default max age of a key in seconds
+   "max": 500, // the maximum number of keys in the cache (for "memory" only)
+   
+   // the below properties only apply to 'redis' provider
+   "host": 'localhost',
+   "port": 6379,
+   "auth_pass": null,
+   "db": 0,
+ }
+}
+```

examples/README.md

@@ -1,42 +0,0 @@
-# Examples
-
-This directory contains example of valid, ready-to-go configurations for Context Bot for the purpose of:
-
-* showcasing what the bot can do
-* providing best practices for writing your configuration
-* providing generally useful configurations **that can be used immediately** or as a jumping-off point for your configuration
-
-### Creating Your Configuration
-
-#### Get the raw contents of the configuration
-
-* In a new tab open the github page for the configuration you want ([example](/examples/repeatActivity/crosspostSpamming.json5))
-* Click the **Raw** button...keep this tab open and move on to the next step
-
-#### Edit your wiki configuration
-
-* Visit the wiki page of the subreddit you want the bot to moderate
-    * Using default bot settings this will be `https://old.reddit.com/r/YOURSUBERDDIT/wiki/botconfig/contextbot`
-    * If the page does not exist create it, otherwise click **Edit**
-* Copy-paste the configuration into the wiki text box
-    * In the previous tab you opened (for the configuration) **Select All** (Ctrl+A), then **Copy**
-    * On the wiki page **Paste** into the text box
-* Save the edited wiki page
-* Ensure the wiki page visibility is restricted
-    * On the wiki page click **settings** (**Page settings** in new reddit)
-    * Check the box for **Only mods may edit and view** and then **save**
-    
-### Examples Overview
-
-* Rules
-  * [Attribution](/examples/attribution)
-  * [Recent Activity](/examples/recentActivity)
-  * [Repeat Activity](/examples/repeatActivity)
-  * [History](/examples/history)
-  * [Author](/examples/author)
-* [Advanced Concepts](/examples/advancedConcepts)
-  * [Rule Sets](/examples/advancedConcepts/ruleSets.json5)
-  * [Name Rules](/examples/advancedConcepts/ruleNameReuse.json5)
-  * [Check Ordering](/examples/advancedConcepts)
-* Subreddit-ready examples
-  * Coming soon...

examples/author/README.md

@@ -1,33 +0,0 @@
-# Author
-
-## Rule
-
-The **Author** rule can if any [AuthorCriteria](https://json-schema.app/view/%23%2Fdefinitions%2FAuthorCriteria?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Freddit-context-bot%2Fmaster%2Fsrc%2FSchema%2FApp.json) from a list are either **included** or **excluded**, depending on which property you put them in.
-
-**AuthorCriteria** that can be checked:
-* name (u/userName)
-* author's subreddit flair text
-* author's subreddit flair css
-* author's subreddit mod status
-
-The Author **Rule** is best used in conjunction with other Rules to short-circuit a Check based on who the Author is. It is easier to use a Rule to do this then to write **author filters** for every Rule (and makes Rules more re-useable).
-
-Consult the [schema](https://json-schema.app/view/%23%2Fdefinitions%2FAuthorRuleJSONConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Freddit-context-bot%2Fmaster%2Fsrc%2FSchema%2FApp.json) for a complete reference of the rule's properties.
-
-### Examples
-
-* Basic examples
-    * [Flair new user Submission](/examples/author/flairNewUserSubmission.json5) - If the Author does not have the `vet` flair then flair the Submission with `New User`
-    * [Flair vetted user Submission](/examples/author/flairNewUserSubmission.json5) - If the Author does have the `vet` flair then flair the Submission with `Vetted`
-* Used with other Rules
-    * [Ignore vetted user](/examples/author/flairNewUserSubmission.json5) - Short-circuit the Check if the Author has the `vet` flair
-    
-## Filter
-
-All **Rules** have an optional `authors` property that takes an [AuthorOptions](https://json-schema.app/view/%23%2Fdefinitions%2FAuthorOptions?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Freddit-context-bot%2Fmaster%2Fsrc%2FSchema%2FApp.json) object. 
-
-**This property works the same as the Author Rule but if any criteria pass the Rule is skipped.** If a Rule is skipped **it does not fail or pass** and so does not affect the outcome of the Check. However, if all Rules on a Check are skipped the Check will fail.
-
-### Examples
-
-* [Skip recent activity check based on author](/examples/author/authorFilter.json5) - Skip a Recent Activity check for a set of subreddits if the Author of the Submission has any set of flairs.

examples/recentActivity/README.md

@@ -1,10 +0,0 @@
-# Recent Activity
-
-The **Recent Activity** rule can check if an Author has made any Submissions/Comments in a list of defined Subreddits.
-
-Consult the [schema](https://json-schema.app/view/%23%2Fdefinitions%2FRecentActivityRuleJSONConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Freddit-context-bot%2Fmaster%2Fsrc%2FSchema%2FApp.json) for a complete reference of the rule's properties.
-
-### Examples
-
-* [Free Karma Subreddits](/examples/recentActivity/freeKarma.json5) - Check if the Author has recently posted in any "free karma" subreddits
-* [Submission in Free Karma Subreddits](/examples/recentActivity/freeKarmaOnSubmission.json5) - Check if the Author has posted the Submission this check is running on in any "free karma" subreddits recently

examples/repeatActivity/README.md

@@ -1,8 +0,0 @@
-# Repeat Activity
-
-The **Repeat Activity** rule will check for patterns of repetition in an Author's Submission/Comment history. Consult the [schema](https://json-schema.app/view/%23%2Fdefinitions%2FRepeatActivityJSONConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Freddit-context-bot%2Fmaster%2Fsrc%2FSchema%2FApp.json) for a complete reference of the rule's properties.
-
-### Examples
-
-* [Crosspost Spamming](/examples/repeatActivity/crosspostSpamming.json5) - Check if an Author is spamming their Submissions across multiple subreddits
-* [Burst-posting](/examples/repeatActivity/burstPosting.json5) - Check if Author is crossposting their Submissions in short bursts

package.json

@@ -1,18 +1,19 @@
 {
   "name": "redditcontextbot",
-  "version": "1.0.0",
+  "version": "0.5.1",
   "description": "",
   "main": "index.js",
   "scripts": {
     "test": "echo \"Error: no tests installed\" && exit 1",
     "build": "tsc",
-    "start": "node server.js",
+    "start": "node src/index.js run",
     "guard": "ts-auto-guard src/JsonConfig.ts",
-    "schema": "npm run -s schema-app & npm run -s schema-ruleset & npm run -s schema-rule & npm run -s schema-action",
+    "schema": "npm run -s schema-app & npm run -s schema-ruleset & npm run -s schema-rule & npm run -s schema-action & npm run -s schema-config",
     "schema-app": "typescript-json-schema tsconfig.json JSONConfig --out src/Schema/App.json --required --tsNodeRegister --refs",
     "schema-ruleset": "typescript-json-schema tsconfig.json RuleSetJson --out src/Schema/RuleSet.json --required --tsNodeRegister --refs",
     "schema-rule": "typescript-json-schema tsconfig.json RuleJson --out src/Schema/Rule.json --required --tsNodeRegister --refs",
     "schema-action": "typescript-json-schema tsconfig.json ActionJson --out src/Schema/Action.json --required --tsNodeRegister --refs",
+    "schema-config": "typescript-json-schema tsconfig.json OperatorJsonConfig --out src/Schema/OperatorConfig.json --required --tsNodeRegister --refs",
     "schemaNotWorking": "./node_modules/.bin/ts-json-schema-generator -f tsconfig.json -p src/JsonConfig.ts -t JSONConfig --out src/Schema/vegaSchema.json",
     "circular": "madge --circular --extensions ts src/index.ts",
     "circular-graph": "madge --image graph.svg --circular --extensions ts src/index.ts"
@@ -24,31 +25,63 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
+    "@awaitjs/express": "^0.8.0",
     "ajv": "^7.2.4",
-    "commander": "^7.2.0",
+    "async": "^3.2.0",
+    "body-parser": "^1.19.0",
+    "cache-manager": "^3.4.4",
+    "cache-manager-redis-store": "^2.0.0",
+    "commander": "^8.0.0",
     "dayjs": "^1.10.5",
+    "deepmerge": "^4.2.2",
+    "ejs": "^3.1.6",
+    "env-cmd": "^10.1.0",
     "es6-error": "^4.1.1",
+    "express": "^4.17.1",
+    "express-session": "^1.17.2",
+    "express-session-cache-manager": "^1.0.2",
+    "express-socket.io-session": "^1.3.5",
     "fast-deep-equal": "^3.1.3",
+    "fuse.js": "^6.4.6",
     "he": "^1.2.0",
+    "js-yaml": "^4.1.0",
     "json5": "^2.2.0",
-    "memory-cache": "^0.2.0",
+    "lodash": "^4.17.21",
+    "lru-cache": "^6.0.0",
     "mustache": "^4.2.0",
+    "node-fetch": "^2.6.1",
     "object-hash": "^2.2.0",
     "p-event": "^4.2.0",
+    "pretty-print-json": "^1.0.3",
     "safe-stable-stringify": "^1.1.1",
     "snoostorm": "^1.5.2",
     "snoowrap": "^1.23.0",
+    "socket.io": "^4.1.3",
+    "tcp-port-used": "^1.0.2",
+    "typescript": "^4.3.4",
+    "webhook-discord": "^3.7.7",
     "winston": "FoxxMD/winston#fbab8de969ecee578981c77846156c7f43b5f01e",
-    "winston-daily-rotate-file": "^4.5.5"
+    "winston-daily-rotate-file": "^4.5.5",
+    "zlib": "^1.0.5"
   },
   "devDependencies": {
     "@tsconfig/node14": "^1.0.0",
+    "@types/async": "^3.2.7",
+    "@types/cache-manager": "^3.4.2",
+    "@types/cache-manager-redis-store": "^2.0.0",
+    "@types/express": "^4.17.13",
+    "@types/express-session": "^1.17.4",
+    "@types/express-socket.io-session": "^1.3.6",
     "@types/he": "^1.1.1",
+    "@types/js-yaml": "^4.0.1",
+    "@types/lodash": "^4.14.171",
+    "@types/lru-cache": "^5.1.1",
     "@types/memory-cache": "^0.2.1",
-    "@types/minimist": "^1.2.1",
     "@types/mustache": "^4.1.1",
     "@types/node": "^15.6.1",
+    "@types/node-fetch": "^2.5.10",
     "@types/object-hash": "^2.1.0",
+    "@types/tcp-port-used": "^1.0.0",
     "ts-auto-guard": "*",
     "ts-json-schema-generator": "^0.93.0",
     "typescript-json-schema": "^0.50.1"

src/Action/ActionFactory.ts

@@ -5,6 +5,10 @@ import {ReportAction, ReportActionJson} from "./ReportAction";
 import {FlairAction, FlairActionJson} from "./SubmissionAction/FlairAction";
 import Action, {ActionJson} from "./index";
 import {Logger} from "winston";
+import {UserNoteAction, UserNoteActionJson} from "./UserNoteAction";
+import ApproveAction, {ApproveActionConfig} from "./ApproveAction";
+import BanAction, {BanActionJson} from "./BanAction";
+import {MessageAction, MessageActionJson} from "./MessageAction";
 
 export function actionFactory
 (config: ActionJson, logger: Logger, subredditName: string): Action {
@@ -19,6 +23,14 @@ export function actionFactory
             return new ReportAction({...config as ReportActionJson, logger, subredditName});
         case 'flair':
             return new FlairAction({...config as FlairActionJson, logger, subredditName});
+        case 'approve':
+            return new ApproveAction({...config as ApproveActionConfig, logger, subredditName});
+        case 'usernote':
+            return new UserNoteAction({...config as UserNoteActionJson, logger, subredditName});
+        case 'ban':
+            return new BanAction({...config as BanActionJson, logger, subredditName});
+        case 'message':
+            return new MessageAction({...config as MessageActionJson, logger, subredditName});
         default:
             throw new Error('rule "kind" was not recognized.');
     }

src/Action/ApproveAction.ts

@@ -0,0 +1,36 @@
+import {ActionJson, ActionConfig} from "./index";
+import Action from "./index";
+import Snoowrap, {Comment, Submission} from "snoowrap";
+import {RuleResult} from "../Rule";
+
+export class ApproveAction extends Action {
+    getKind() {
+        return 'Approve';
+    }
+
+    async process(item: Comment | Submission, ruleResults: RuleResult[], runtimeDryrun?: boolean): Promise<void> {
+        const dryRun = runtimeDryrun || this.dryRun;
+        //snoowrap typing issue, thinks comments can't be locked
+        // @ts-ignore
+        if (item.approved) {
+            this.logger.warn('Item is already approved');
+        }
+        if (!dryRun) {
+            // @ts-ignore
+            await item.approve();
+        }
+    }
+}
+
+export interface ApproveActionConfig extends ActionConfig {
+
+}
+
+/**
+ * Ban the Author of the Activity this Check is run on
+ * */
+export interface ApproveActionJson extends ApproveActionConfig, ActionJson {
+    kind: 'approve'
+}
+
+export default ApproveAction;

src/Action/BanAction.ts

@@ -0,0 +1,110 @@
+import {ActionJson, ActionConfig, ActionOptions} from "./index";
+import Action from "./index";
+import Snoowrap, {Comment, Submission} from "snoowrap";
+import {RuleResult} from "../Rule";
+import {renderContent} from "../Utils/SnoowrapUtils";
+import {Footer} from "../Common/interfaces";
+
+export class BanAction extends Action {
+
+    message?: string;
+    reason?: string;
+    duration?: number;
+    note?: string;
+    footer?: false | string;
+
+    constructor(options: BanActionOptions) {
+        super(options);
+        const {
+            message,
+            reason,
+            duration,
+            note,
+            footer,
+        } = options;
+        this.footer = footer;
+        this.message = message;
+        this.reason = reason;
+        this.duration = duration;
+        this.note = note;
+    }
+
+    getKind() {
+        return 'Ban';
+    }
+
+    async process(item: Comment | Submission, ruleResults: RuleResult[], runtimeDryrun?: boolean): Promise<void> {
+        const dryRun = runtimeDryrun || this.dryRun;
+        const content = this.message === undefined ? undefined : await this.resources.getContent(this.message, item.subreddit);
+        const renderedBody = content === undefined ? undefined : await renderContent(content, item, ruleResults, this.resources.userNotes);
+        const renderedContent = renderedBody === undefined ? undefined : `${renderedBody}${await this.resources.generateFooter(item, this.footer)}`;
+
+        let banPieces = [];
+        banPieces.push(`Message: ${renderedContent === undefined ? 'None' : `${renderedContent.length > 100 ? `\r\n${renderedContent}` : renderedContent}`}`);
+        banPieces.push(`Reason:  ${this.reason || 'None'}`);
+        banPieces.push(`Note:    ${this.note || 'None'}`);
+        const durText = this.duration === undefined ? 'permanently' : `for ${this.duration} days`;
+        this.logger.info(`Banning ${item.author.name} ${durText}${this.reason !== undefined ? ` (${this.reason})` : ''}`);
+        this.logger.verbose(`\r\n${banPieces.join('\r\n')}`);
+        if (!dryRun) {
+            // @ts-ignore
+            const fetchedSub = await item.subreddit.fetch();
+            const fetchedName = await item.author.name;
+            await fetchedSub.banUser({
+                name: fetchedName,
+                banMessage: renderedContent === undefined ? undefined : renderedContent,
+                banReason: this.reason,
+                banNote: this.note,
+                duration: this.duration
+            });
+        }
+    }
+}
+
+export interface BanActionConfig extends ActionConfig, Footer {
+    /**
+     * The message that is sent in the ban notification. `message` is interpreted as reddit-flavored Markdown.
+     *
+     * If value starts with `wiki:` then the proceeding value will be used to get a wiki page
+     *
+     * EX `wiki:botconfig/mybot` tries to get `https://reddit.com/mySubredditExample/wiki/botconfig/mybot`
+     *
+     * EX `this is plain text` => "this is plain text"
+     *
+     * EX `this is **bold** markdown text` => "this is **bold** markdown text"
+     *
+     * @examples ["This is the content of a comment/report/usernote", "this is **bold** markdown text", "wiki:botconfig/acomment" ]
+     * */
+    message?: string
+    /**
+     * Reason for ban.
+     * @maxLength 100
+     * @examples ["repeat spam"]
+     * */
+    reason?: string
+    /**
+     * Number of days to ban the Author. If not specified Author will be banned permanently.
+     * @minimum 1
+     * @maximum 999
+     * @examples [90]
+     * */
+    duration?: number
+    /**
+     * A mod note for this ban
+     * @maxLength 100
+     * @examples ["Sock puppet for u/AnotherUser"]
+     * */
+    note?: string
+}
+
+export interface BanActionOptions extends BanActionConfig, ActionOptions {
+}
+
+/**
+ * Ban the Author of the Activity this Check is run on
+ * */
+export interface BanActionJson extends BanActionConfig, ActionJson {
+    kind: 'ban',
+}
+
+export default BanAction;

src/Action/CommentAction.ts

@@ -2,7 +2,7 @@ import Action, {ActionJson, ActionOptions} from "./index";
 import {Comment} from "snoowrap";
 import Submission from "snoowrap/dist/objects/Submission";
 import {renderContent} from "../Utils/SnoowrapUtils";
-import {RichContent} from "../Common/interfaces";
+import {Footer, RequiredRichContent, RichContent} from "../Common/interfaces";
 import {RuleResult} from "../Rule";
 
 export class CommentAction extends Action {
@@ -10,6 +10,7 @@ export class CommentAction extends Action {
     lock: boolean = false;
     sticky: boolean = false;
     distinguish: boolean = false;
+    footer?: false | string;
 
     constructor(options: CommentActionOptions) {
         super(options);
@@ -18,7 +19,9 @@ export class CommentAction extends Action {
             lock = false,
             sticky = false,
             distinguish = false,
+            footer,
         } = options;
+        this.footer = footer;
         this.content = content;
         this.lock = lock;
         this.sticky = sticky;
@@ -29,30 +32,40 @@ export class CommentAction extends Action {
         return 'Comment';
     }
 
-    async process(item: Comment | Submission, ruleResults: RuleResult[]): Promise<void> {
-        const content = await this.cache.getContent(this.content, item.subreddit);
-        const renderedContent = await renderContent(content, item, ruleResults);
-        this.logger.verbose(`Contents:\r\n${renderedContent}`);
-        // @ts-ignore
-        const reply: Comment = await item.reply(renderedContent);
+    async process(item: Comment | Submission, ruleResults: RuleResult[], runtimeDryrun?: boolean): Promise<void> {
+        const dryRun = runtimeDryrun || this.dryRun;
+        const content = await this.resources.getContent(this.content, item.subreddit);
+        const body = await renderContent(content, item, ruleResults, this.resources.userNotes);
+
+        const footer = await this.resources.generateFooter(item, this.footer);
+
+        const renderedContent = `${body}${footer}`;
+        this.logger.verbose(`Contents:\r\n${renderedContent.length > 100 ? `\r\n${renderedContent}` : renderedContent}`);
+
+        if(item.archived) {
+            this.logger.warn('Cannot comment because Item is archived');
+            return;
+        }
+        let reply: Comment;
+        if(!dryRun) {
+            // @ts-ignore
+           reply = await item.reply(renderedContent);
+        }
         if (this.lock) {
-            if(item instanceof Submission) {
-                if(!this.dryRun) {
-                    // @ts-ignore
-                    await item.lock();
-                }
-            } else {
-                this.logger.warn('Snoowrap does not support locking Comments');
+            if (!dryRun) {
+                // snoopwrap typing issue, thinks comments can't be locked
+                // @ts-ignore
+                await item.lock();
             }
         }
-        if (this.distinguish && !this.dryRun) {
+        if (this.distinguish && !dryRun) {
             // @ts-ignore
             await reply.distinguish({sticky: this.sticky});
         }
     }
 }
 
-export interface CommentActionConfig extends RichContent {
+export interface CommentActionConfig extends RequiredRichContent, Footer {
     /**
      * Lock the comment after creation?
      * */
@@ -67,12 +80,12 @@ export interface CommentActionConfig extends RichContent {
     distinguish?: boolean,
 }
 
-export interface CommentActionOptions extends CommentActionConfig,ActionOptions {
+export interface CommentActionOptions extends CommentActionConfig, ActionOptions {
 }
 
 /**
  * Reply to the Activity. For a submission the reply will be a top-level comment.
  * */
 export interface CommentActionJson extends CommentActionConfig, ActionJson {
-
+kind: 'comment'
 }

src/Action/LockAction.ts

@@ -8,14 +8,17 @@ export class LockAction extends Action {
         return 'Lock';
     }
 
-    async process(item: Comment|Submission, ruleResults: RuleResult[]): Promise<void> {
-        if (item instanceof Submission) {
-            if(!this.dryRun) {
-                // @ts-ignore
-                await item.lock();
-            }
-        } else {
-            this.logger.warn('Snoowrap does not support locking Comments');
+    async process(item: Comment | Submission, ruleResults: RuleResult[], runtimeDryrun?: boolean): Promise<void> {
+        const dryRun = runtimeDryrun || this.dryRun;
+        //snoowrap typing issue, thinks comments can't be locked
+        // @ts-ignore
+        if (item.locked) {
+            this.logger.warn('Item is already locked');
+        }
+        if (!dryRun) {
+            //snoowrap typing issue, thinks comments can't be locked
+            // @ts-ignore
+            await item.lock();
         }
     }
 }
@@ -28,7 +31,7 @@ export interface LockActionConfig extends ActionConfig {
  * Lock the Activity
  * */
 export interface LockActionJson extends LockActionConfig, ActionJson {
-
+kind: 'lock'
 }
 
 export default LockAction;

src/Action/MessageAction.ts

@@ -0,0 +1,94 @@
+import Action, {ActionJson, ActionOptions} from "./index";
+import {Comment, ComposeMessageParams} from "snoowrap";
+import Submission from "snoowrap/dist/objects/Submission";
+import {renderContent, singleton} from "../Utils/SnoowrapUtils";
+import {Footer, RequiredRichContent, RichContent} from "../Common/interfaces";
+import {RuleResult} from "../Rule";
+import {boolToString} from "../util";
+
+export class MessageAction extends Action {
+    content: string;
+    lock: boolean = false;
+    sticky: boolean = false;
+    distinguish: boolean = false;
+    footer?: false | string;
+
+    title?: string;
+    asSubreddit: boolean;
+
+    constructor(options: MessageActionOptions) {
+        super(options);
+        const {
+            content,
+            asSubreddit,
+            title,
+            footer,
+        } = options;
+        this.footer = footer;
+        this.content = content;
+        this.asSubreddit = asSubreddit;
+        this.title = title;
+    }
+
+    getKind() {
+        return 'Message';
+    }
+
+    async process(item: Comment | Submission, ruleResults: RuleResult[], runtimeDryrun?: boolean): Promise<void> {
+        const dryRun = runtimeDryrun || this.dryRun;
+        const content = await this.resources.getContent(this.content);
+        const body = await renderContent(content, item, ruleResults, this.resources.userNotes);
+
+        const footer = await this.resources.generateFooter(item, this.footer);
+
+        const renderedContent = `${body}${footer}`;
+        // @ts-ignore
+        const author = await item.author.fetch() as RedditUser;
+
+        const client = singleton.getClient();
+
+        const msgOpts: ComposeMessageParams = {
+            to: author,
+            text: renderedContent,
+            // @ts-ignore
+            fromSubreddit: this.asSubreddit ? await item.subreddit.fetch() : undefined,
+            subject: this.title || `Concerning your ${item instanceof Submission ? 'Submission' : 'Comment'}`,
+        };
+
+        const msgPreview = `\r\n
+        TO: ${author.name}\r\n
+        Subject: ${msgOpts.subject}\r\n
+        Sent As Modmail: ${boolToString(this.asSubreddit)}\r\n\r\n
+        ${renderedContent}`;
+
+        this.logger.verbose(`Message Preview => \r\n ${msgPreview}`);
+
+        if (!dryRun) {
+            await client.composeMessage(msgOpts);
+        }
+    }
+}
+
+export interface MessageActionConfig extends RequiredRichContent, Footer {
+    /**
+     * Should this message be sent from modmail (as the subreddit) or as the bot user?
+     * */
+    asSubreddit: boolean
+
+    /**
+     * The title of the message
+     *
+     * If not specified will be defaulted to `Concerning your [Submission/Comment]`
+     * */
+    title?: string
+}
+
+export interface MessageActionOptions extends MessageActionConfig, ActionOptions {
+}
+
+/**
+ * Send a private message to the Author of the Activity.
+ * */
+export interface MessageActionJson extends MessageActionConfig, ActionJson {
+    kind: 'message'
+}

src/Action/RemoveAction.ts

@@ -2,14 +2,22 @@ import {ActionJson, ActionConfig} from "./index";
 import Action from "./index";
 import Snoowrap, {Comment, Submission} from "snoowrap";
 import {RuleResult} from "../Rule";
+import {activityIsRemoved} from "../Utils/SnoowrapUtils";
 
 export class RemoveAction extends Action {
     getKind() {
         return 'Remove';
     }
 
-    async process(item: Comment|Submission, ruleResults: RuleResult[]): Promise<void> {
-        if(!this.dryRun) {
+    async process(item: Comment | Submission, ruleResults: RuleResult[], runtimeDryrun?: boolean): Promise<void> {
+        const dryRun = runtimeDryrun || this.dryRun;
+        // issue with snoowrap typings, doesn't think prop exists on Submission
+        // @ts-ignore
+        if (activityIsRemoved(item)) {
+            this.logger.warn('Item is already removed');
+            return;
+        }
+        if (!dryRun) {
             // @ts-ignore
             await item.remove();
         }
@@ -24,5 +32,5 @@ export interface RemoveActionConfig extends ActionConfig {
  * Remove the Activity
  * */
 export interface RemoveActionJson extends RemoveActionConfig, ActionJson {
-
+kind: 'remove'
 }

src/Action/ReportAction.ts

@@ -4,6 +4,7 @@ import Snoowrap, {Comment, Submission} from "snoowrap";
 import {truncateStringToLength} from "../util";
 import {renderContent} from "../Utils/SnoowrapUtils";
 import {RuleResult} from "../Rule";
+import {RichContent} from "../Common/interfaces";
 
 // https://www.reddit.com/dev/api/oauth#POST_api_report
 // denotes 100 characters maximum
@@ -22,23 +23,20 @@ export class ReportAction extends Action {
         return 'Report';
     }
 
-    async process(item: Comment | Submission, ruleResults: RuleResult[]): Promise<void> {
-        const content = await this.cache.getContent(this.content, item.subreddit);
-        const renderedContent = await renderContent(content, item, ruleResults);
+    async process(item: Comment | Submission, ruleResults: RuleResult[], runtimeDryrun?: boolean): Promise<void> {
+        const dryRun = runtimeDryrun || this.dryRun;
+        const content = await this.resources.getContent(this.content, item.subreddit);
+        const renderedContent = await renderContent(content, item, ruleResults, this.resources.userNotes);
         this.logger.verbose(`Contents:\r\n${renderedContent}`);
         const truncatedContent = reportTrunc(renderedContent);
-        if(!this.dryRun) {
+        if(!dryRun) {
             // @ts-ignore
             await item.report({reason: truncatedContent});
         }
     }
 }
 
-export interface ReportActionConfig {
-    /**
-     * The text of the report. If longer than 100 characters will be truncated to "[content]..."
-     * */
-    content: string,
+export interface ReportActionConfig extends RichContent {
 }
 
 export interface ReportActionOptions extends ReportActionConfig, ActionOptions {
@@ -48,5 +46,5 @@ export interface ReportActionOptions extends ReportActionConfig, ActionOptions {
  * Report the Activity
  * */
 export interface ReportActionJson extends ReportActionConfig, ActionJson {
-
+    kind: 'report'
 }

src/Action/SubmissionAction/FlairAction.ts

@@ -55,5 +55,5 @@ export interface FlairActionOptions extends FlairActionConfig,ActionOptions {
  * Flair the Submission
  * */
 export interface FlairActionJson extends FlairActionConfig, ActionJson {
-
+kind: 'flair'
 }

src/Action/SubmissionAction/index.js

@@ -1,11 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SubmissionAction = void 0;
-const index_1 = __importDefault(require("../index"));
-class SubmissionAction extends index_1.default {
-}
-exports.SubmissionAction = SubmissionAction;
-//# sourceMappingURL=index.js.map

src/Action/SubmissionAction/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;;;;;AAAA,qDAA8C;AAE9C,MAAsB,gBAAiB,SAAQ,eAAM;CAEpD;AAFD,4CAEC"}

src/Action/UserNoteAction.ts

@@ -0,0 +1,66 @@
+import {ActionJson, ActionConfig, ActionOptions} from "./index";
+import Action from "./index";
+import {Comment} from "snoowrap";
+import {renderContent} from "../Utils/SnoowrapUtils";
+import {RuleResult} from "../Rule";
+import {UserNote, UserNoteJson} from "../Subreddit/UserNotes";
+import Submission from "snoowrap/dist/objects/Submission";
+
+
+export class UserNoteAction extends Action {
+    content: string;
+    type: string;
+    allowDuplicate: boolean;
+
+    constructor(options: UserNoteActionOptions) {
+        super(options);
+        const {type, content = '', allowDuplicate = false} = options;
+        this.type = type;
+        this.content = content;
+        this.allowDuplicate = allowDuplicate;
+    }
+
+    getKind() {
+        return 'User Note';
+    }
+
+    async process(item: Comment | Submission, ruleResults: RuleResult[], runtimeDryrun?: boolean): Promise<void> {
+        const dryRun = runtimeDryrun || this.dryRun;
+        const content = await this.resources.getContent(this.content, item.subreddit);
+        const renderedContent = await renderContent(content, item, ruleResults, this.resources.userNotes);
+        this.logger.verbose(`Note:\r\n(${this.type}) ${renderedContent}`);
+
+        if (!this.allowDuplicate) {
+            const notes = await this.resources.userNotes.getUserNotes(item.author);
+            const existingNote = notes.find((x) => x.link.includes(item.id));
+            if (existingNote) {
+                this.logger.info(`Will not add note because one already exists for this Activity (${existingNote.time.local().format()}) and allowDuplicate=false`);
+                return;
+            }
+        }
+        if (!dryRun) {
+            await this.resources.userNotes.addUserNote(item, this.type, renderedContent);
+        } else if (!await this.resources.userNotes.warningExists(this.type)) {
+            this.logger.warn(`UserNote type '${this.type}' does not exist. If you meant to use this please add it through Toolbox first.`);
+        }
+    }
+}
+
+export interface UserNoteActionConfig extends ActionConfig,UserNoteJson {
+    /**
+     * Add Note even if a Note already exists for this Activity
+     * @examples [false]
+     * @default false
+     * */
+    allowDuplicate?: boolean,
+}
+
+export interface UserNoteActionOptions extends UserNoteActionConfig, ActionOptions {
+}
+
+/**
+ * Add a Toolbox User Note to the Author of this Activity
+ * */
+export interface UserNoteActionJson extends UserNoteActionConfig, ActionJson {
+    kind: 'usernote'
+}

src/Action/index.ts

@@ -1,37 +1,94 @@
 import {Comment, Submission} from "snoowrap";
 import {Logger} from "winston";
 import {RuleResult} from "../Rule";
-import CacheManager, {SubredditCache} from "../Subreddit/SubredditCache";
+import ResourceManager, {SubredditResources} from "../Subreddit/SubredditResources";
+import {ChecksActivityState, TypedActivityStates} from "../Common/interfaces";
+import Author, {AuthorOptions} from "../Author/Author";
 
 export abstract class Action {
     name?: string;
     logger: Logger;
-    cache: SubredditCache;
+    resources: SubredditResources;
+    authorIs: AuthorOptions;
+    itemIs: TypedActivityStates;
     dryRun: boolean;
+    enabled: boolean;
 
     constructor(options: ActionOptions) {
         const {
+            enable = true,
             name = this.getKind(),
             logger,
             subredditName,
             dryRun = false,
+            authorIs: {
+                include = [],
+                exclude = [],
+            } = {},
+            itemIs = [],
         } = options;
 
         this.name = name;
         this.dryRun = dryRun;
-        this.cache = CacheManager.get(subredditName);
-        const uniqueName = this.name === this.getKind() ? this.getKind() : `${this.getKind()} - ${this.name}`;
-        this.logger = logger.child({labels: ['Action', uniqueName]});
+        this.enabled = enable;
+        this.resources = ResourceManager.get(subredditName) as SubredditResources;
+        this.logger = logger.child({labels: [`Action ${this.getActionUniqueName()}`]});
+
+        this.authorIs = {
+            exclude: exclude.map(x => new Author(x)),
+            include: include.map(x => new Author(x)),
+        }
+
+        this.itemIs = itemIs;
     }
 
     abstract getKind(): string;
 
-    async handle(item: Comment | Submission, ruleResults: RuleResult[]): Promise<void> {
-        await this.process(item, ruleResults);
-        this.logger.debug(`${this.dryRun ? 'DRYRUN - ' : ''}Done`);
+    getActionUniqueName() {
+        return this.name === this.getKind() ? this.getKind() : `${this.getKind()} - ${this.name}`;
     }
 
-    abstract process(item: Comment | Submission, ruleResults: RuleResult[]): Promise<void>;
+    async handle(item: Comment | Submission, ruleResults: RuleResult[], runtimeDryrun?: boolean): Promise<void> {
+        const dryRun = runtimeDryrun || this.dryRun;
+        let actionRun = false;
+        const itemPass = await this.resources.testItemCriteria(item, this.itemIs);
+        if (!itemPass) {
+            this.logger.verbose(`Activity did not pass 'itemIs' test, Action not run`);
+            return;
+        }
+        const authorRun = async () => {
+            if (this.authorIs.include !== undefined && this.authorIs.include.length > 0) {
+                for (const auth of this.authorIs.include) {
+                    if (await this.resources.testAuthorCriteria(item, auth)) {
+                        await this.process(item, ruleResults, runtimeDryrun);
+                        return true;
+                    }
+                }
+                this.logger.verbose('Inclusive author criteria not matched, Action not run');
+                return false;
+            }
+            if (!actionRun && this.authorIs.exclude !== undefined && this.authorIs.exclude.length > 0) {
+                for (const auth of this.authorIs.exclude) {
+                    if (await this.resources.testAuthorCriteria(item, auth, false)) {
+                        await this.process(item, ruleResults, runtimeDryrun);
+                        return true;
+                    }
+                }
+                this.logger.verbose('Exclusive author criteria not matched, Action not run');
+                return false;
+            }
+            return null;
+        }
+        const authorRunResults = await authorRun();
+        if (null === authorRunResults) {
+            await this.process(item, ruleResults, runtimeDryrun);
+        } else if (!authorRunResults) {
+            return;
+        }
+        this.logger.verbose(`${dryRun ? 'DRYRUN - ' : ''}Done`);
+    }
+
+    abstract process(item: Comment | Submission, ruleResults: RuleResult[], runtimeDryun?: boolean): Promise<void>;
 }
 
 export interface ActionOptions extends ActionConfig {
@@ -39,28 +96,51 @@ export interface ActionOptions extends ActionConfig {
     subredditName: string;
 }
 
-export interface ActionConfig {
+export interface ActionConfig extends ChecksActivityState {
     /**
      * An optional, but highly recommended, friendly name for this Action. If not present will default to `kind`.
      *
      * Can only contain letters, numbers, underscore, spaces, and dashes
      *
      * @pattern ^[a-zA-Z]([\w -]*[\w])?$
+     * @examples ["myDescriptiveAction"]
      * */
     name?: string;
     /**
      * If `true` the Action will not make the API request to Reddit to perform its action.
      *
      * @default false
+     * @examples [false, true]
      * */
     dryRun?: boolean;
+
+    /**
+     * If present then these Author criteria are checked before running the Action. If criteria fails then the Action is not run.
+     * */
+    authorIs?: AuthorOptions
+
+    /**
+     * A list of criteria to test the state of the `Activity` against before running the Action.
+     *
+     * If any set of criteria passes the Action will be run.
+     *
+     * */
+    itemIs?: TypedActivityStates
+
+    /**
+     * If set to `false` the Action will not be run
+     *
+     * @default true
+     * @examples [true]
+     * */
+    enable?: boolean
 }
 
 export interface ActionJson extends ActionConfig {
     /**
      * The type of action that will be performed
      */
-    kind: 'comment' | 'lock' | 'remove' | 'report' | 'flair'
+    kind: 'comment' | 'lock' | 'remove' | 'report' | 'approve' | 'ban' | 'flair' | 'usernote' | 'message'
 }
 
 export const isActionJson = (obj: object): obj is ActionJson => {

src/App.ts

@@ -1,13 +1,26 @@
-import Snoowrap from "snoowrap";
+import Snoowrap, {Subreddit} from "snoowrap";
 import {Manager} from "./Subreddit/Manager";
 import winston, {Logger} from "winston";
-import {argParseInt, labelledFormat, parseBool, sleep} from "./util";
-import snoowrap from "snoowrap";
+import {
+    argParseInt,
+    createRetryHandler, formatNumber,
+    labelledFormat, logLevels,
+    parseBool, parseDuration,
+    parseFromJsonOrYamlToObject,
+    parseSubredditName,
+    sleep
+} from "./util";
 import pEvent from "p-event";
-import JSON5 from 'json5';
 import EventEmitter from "events";
-import CacheManager from './Subreddit/SubredditCache';
-import dayjs from "dayjs";
+import CacheManager from './Subreddit/SubredditResources';
+import dayjs, {Dayjs} from "dayjs";
+import LoggedError from "./Utils/LoggedError";
+import {ProxiedSnoowrap, RequestTrackingSnoowrap} from "./Utils/SnoowrapClients";
+import {ModQueueStream, UnmoderatedStream} from "./Subreddit/Streams";
+import {getLogger} from "./Utils/loggerFactory";
+import {DurationString, OperatorConfig, PAUSED, RUNNING, STOPPED, SYSTEM, USER} from "./Common/interfaces";
+import { Duration } from "dayjs/plugin/duration";
+import {singleton} from "./Utils/SnoowrapUtils";
 
 const {transports} = winston;
 
@@ -15,6 +28,8 @@ const snooLogWrapper = (logger: Logger) => {
     return {
         warn: (...args: any[]) => logger.warn(args.slice(0, 2).join(' '), [args.slice(2)]),
         debug: (...args: any[]) => logger.debug(args.slice(0, 2).join(' '), [args.slice(2)]),
+        info: (...args: any[]) => logger.info(args.slice(0, 2).join(' '), [args.slice(2)]),
+        trace: (...args: any[]) => logger.debug(args.slice(0, 2).join(' '), [args.slice(2)]),
     }
 }
 
@@ -27,134 +42,210 @@ export class App {
     wikiLocation: string;
     dryRun?: true | undefined;
     heartbeatInterval: number;
-    apiLimitWarning: number;
+    nextHeartbeat?: Dayjs;
+    heartBeating: boolean = false;
+    //apiLimitWarning: number;
+    softLimit: number | string = 250;
+    hardLimit: number | string = 50;
+    nannyMode?: 'soft' | 'hard';
+    nextExpiration!: Dayjs;
+    botName!: string;
+    botLink!: string;
+    maxWorkers: number;
+    startedAt: Dayjs = dayjs();
+    sharedModqueue: boolean = false;
 
-    constructor(options: any = {}) {
+    apiSample: number[] = [];
+    interval: any;
+    apiRollingAvg: number = 0;
+    apiEstDepletion?: Duration;
+    depletedInSecs: number = 0;
+
+    constructor(config: OperatorConfig) {
         const {
-            subreddits = [],
-            clientId,
-            clientSecret,
-            accessToken,
-            refreshToken,
-            logDir = process.env.LOG_DIR || `${process.cwd()}/logs`,
-            logLevel = process.env.LOG_LEVEL || 'info',
-            wikiConfig = process.env.WIKI_CONFIG || 'botconfig/contextbot',
-            snooDebug = process.env.SNOO_DEBUG || false,
-            dryRun = process.env.DRYRUN || false,
-            heartbeat = process.env.HEARTBEAT || 300,
-            apiLimitWarning = process.env.API_REMAINING || 250,
-            version,
-            authorTTL = process.env.AUTHOR_TTL || 10000,
-            disableCache = process.env.DISABLE_CACHE || false,
-        } = options;
+            operator: {
+              botName,
+                name,
+            },
+            subreddits: {
+              names = [],
+              wikiConfig,
+                dryRun,
+                heartbeatInterval,
+            },
+            credentials: {
+                clientId,
+                clientSecret,
+                refreshToken,
+                accessToken,
+            },
+            snoowrap: {
+                proxy,
+                debug,
+            },
+            polling: {
+                sharedMod,
+            },
+            queue: {
+              maxWorkers,
+            },
+            caching: {
+                authorTTL,
+                provider: {
+                    store
+                }
+            },
+            api: {
+                softLimit,
+                hardLimit,
+            }
+        } = config;
 
-        CacheManager.authorTTL = argParseInt(authorTTL);
-        CacheManager.enabled = !parseBool(disableCache);
+        CacheManager.setDefaultsFromConfig(config);
 
         this.dryRun = parseBool(dryRun) === true ? true : undefined;
-        this.heartbeatInterval = argParseInt(heartbeat);
-        this.apiLimitWarning = argParseInt(apiLimitWarning);
+        this.heartbeatInterval = heartbeatInterval;
+        //this.apiLimitWarning = argParseInt(apiLimitWarning);
+        this.softLimit = softLimit;
+        this.hardLimit = hardLimit;
         this.wikiLocation = wikiConfig;
-
-        const consoleTransport = new transports.Console();
-
-        const myTransports = [
-            consoleTransport,
-        ];
-
-        if (logDir !== false) {
-            let logPath = logDir;
-            if (logPath === true) {
-                logPath = `${process.cwd()}/logs`;
-            }
-            const rotateTransport = new winston.transports.DailyRotateFile({
-                dirname: logPath,
-                createSymlink: true,
-                symlinkName: 'contextBot-current.log',
-                filename: 'contextBot-%DATE%.log',
-                datePattern: 'YYYY-MM-DD',
-                maxSize: '5m'
-            });
-            // @ts-ignore
-            myTransports.push(rotateTransport);
+        this.sharedModqueue = sharedMod;
+        if(botName !== undefined) {
+            this.botName = botName;
         }
 
-        const loggerOptions = {
-            level: logLevel || 'info',
-            format: labelledFormat(),
-            transports: myTransports,
-            levels: {
-                error: 0,
-                warn: 1,
-                info: 2,
-                http: 3,
-                verbose: 4,
-                debug: 5,
-                trace: 5,
-                silly: 6
-            }
-        };
+        this.logger = getLogger(config.logging);
 
-        winston.loggers.add('default', loggerOptions);
+        this.logger.info(`Operators: ${name.length === 0 ? 'None Specified' : name.join(', ')}`)
 
-        this.logger = winston.loggers.get('default');
+        let mw = maxWorkers;
+        if(maxWorkers < 1) {
+            this.logger.warn(`Max queue workers must be greater than or equal to 1 (Specified: ${maxWorkers})`);
+            mw = 1;
+        }
+        this.maxWorkers = mw;
 
         if (this.dryRun) {
             this.logger.info('Running in DRYRUN mode');
         }
 
-        let subredditsArg = [];
-        if (subreddits !== undefined) {
-            if (Array.isArray(subreddits)) {
-                subredditsArg = subreddits;
-            } else {
-                subredditsArg = subreddits.split(',');
-            }
-        }
-        this.subreddits = subredditsArg;
+        this.subreddits = names.map(parseSubredditName);
 
         const creds = {
-            userAgent: `web:contextBot:${version}`,
+            userAgent: `web:contextBot:dev`,
             clientId,
             clientSecret,
             refreshToken,
             accessToken,
         };
 
-        let shouldDebug = parseBool(snooDebug);
-        let snooLogger;
-        if (shouldDebug) {
-            const clogger = this.logger.child({labels: ['Snoowrap']});
-            snooLogger = snooLogWrapper(clogger);
+        const missingCreds = [];
+        for(const [k,v] of Object.entries(creds)) {
+            if(v === undefined || v === '' || v === null) {
+                missingCreds.push(k);
+            }
         }
-        this.client = new snoowrap(creds);
+        if(missingCreds.length > 0) {
+            this.logger.error('There are credentials missing that would prevent initializing the Reddit API Client and subsequently the rest of the application');
+            this.logger.error(`Missing credentials: ${missingCreds.join(', ')}`)
+            this.logger.info(`If this is a first-time setup use the 'web' command for a web-based guide to configuring your application`);
+            this.logger.info(`Or check the USAGE section of the readme for the correct naming of these arguments/environment variables`);
+            throw new LoggedError(`Missing credentials: ${missingCreds.join(', ')}`);
+        }
+
+        this.client = proxy === undefined ? new Snoowrap(creds) : new ProxiedSnoowrap({...creds, proxy});
         this.client.config({
             warnings: true,
             maxRetryAttempts: 5,
-            debug: shouldDebug,
-            // @ts-ignore
-            logger: snooLogger,
+            debug,
+            logger: snooLogWrapper(this.logger.child({labels: ['Snoowrap']})),
             continueAfterRatelimitError: true,
         });
+
+        singleton.setClient(this.client);
+
+        const retryHandler = createRetryHandler({maxRequestRetry: 8, maxOtherRetry: 1}, this.logger);
+
+        const modStreamErrorListener = (name: string) => async (err: any) => {
+            this.logger.error('Polling error occurred', err);
+            const shouldRetry = await retryHandler(err);
+            if(shouldRetry) {
+                defaultUnmoderatedStream.startInterval();
+            } else {
+                for(const m of this.subManagers) {
+                    if(m.modStreamCallbacks.size > 0) {
+                        m.notificationManager.handle('runStateChanged', `${name.toUpperCase()} Polling Stopped`, 'Encountered too many errors from Reddit while polling. Will try to restart on next heartbeat.');
+                    }
+                }
+                this.logger.error(`Mod stream ${name.toUpperCase()} encountered too many errors while polling. Will try to restart on next heartbeat.`);
+            }
+        }
+
+        const defaultUnmoderatedStream = new UnmoderatedStream(this.client, {subreddit: 'mod'});
+        // @ts-ignore
+        defaultUnmoderatedStream.on('error', modStreamErrorListener('unmoderated'));
+        const defaultModqueueStream = new ModQueueStream(this.client, {subreddit: 'mod'});
+        // @ts-ignore
+        defaultModqueueStream.on('error', modStreamErrorListener('modqueue'));
+        CacheManager.modStreams.set('unmoderated', defaultUnmoderatedStream);
+        CacheManager.modStreams.set('modqueue', defaultModqueueStream);
+    }
+
+    async onTerminate(reason = 'The application was shutdown') {
+        for(const m of this.subManagers) {
+            await m.notificationManager.handle('runStateChanged', 'Application Shutdown', reason);
+        }
+    }
+
+    async testClient() {
+        try {
+            // @ts-ignore
+            await this.client.getMe();
+            this.logger.info('Test API call successful');
+        } catch (err) {
+            this.logger.error('An error occurred while trying to initialize the Reddit API Client which would prevent the entire application from running.');
+            if(err.name === 'StatusCodeError') {
+                const authHeader = err.response.headers['www-authenticate'];
+                if (authHeader !== undefined && authHeader.includes('insufficient_scope')) {
+                    this.logger.error('Reddit responded with a 403 insufficient_scope. Please ensure you have chosen the correct scopes when authorizing your account.');
+                } else if(err.statusCode === 401) {
+                    this.logger.error('It is likely a credential is missing or incorrect. Check clientId, clientSecret, refreshToken, and accessToken');
+                }
+                this.logger.error(`Error Message: ${err.message}`);
+            } else {
+                this.logger.error(err);
+            }
+            err.logged = true;
+            throw err;
+        }
     }
 
     async buildManagers(subreddits: string[] = []) {
         let availSubs = [];
-        const name = await this.client.getMe().name;
+        // @ts-ignore
+        const user = await this.client.getMe().fetch();
+        this.botLink = `https://reddit.com/user/${user.name}`;
         this.logger.info(`Reddit API Limit Remaining: ${this.client.ratelimitRemaining}`);
-        this.logger.info(`Authenticated Account: /u/${name}`);
+        this.logger.info(`Authenticated Account: u/${user.name}`);
+
+        const botNameFromConfig = this.botName !== undefined;
+        if(this.botName === undefined) {
+            this.botName = `u/${user.name}`;
+        }
+        this.logger.info(`Bot Name${botNameFromConfig ? ' (from config)' : ''}: ${this.botName}`);
+
         for (const sub of await this.client.getModeratedSubreddits()) {
             // TODO don't know a way to check permissions yet
             availSubs.push(sub);
         }
-        this.logger.info(`/u/${name} is a moderator of these subreddits: ${availSubs.map(x => x.display_name_prefixed).join(', ')}`);
+        this.logger.info(`${this.botName} is a moderator of these subreddits: ${availSubs.map(x => x.display_name_prefixed).join(', ')}`);
 
-        let subsToRun = [];
-        const subsToUse = subreddits.length > 0 ? subreddits : this.subreddits;
+        let subsToRun: Subreddit[] = [];
+        const subsToUse = subreddits.length > 0 ? subreddits.map(parseSubredditName) : this.subreddits;
         if (subsToUse.length > 0) {
-            this.logger.info(`User-defined subreddit constraints detected (CLI argument or environmental variable), will try to run on: ${subsToUse.join(', ')}`);
+            this.logger.info(`Operator-defined subreddit constraints detected (CLI argument or environmental variable), will try to run on: ${subsToUse.join(', ')}`);
             for (const sub of subsToUse) {
-                const asub = availSubs.find(x => x.display_name.toLowerCase() === sub.trim().toLowerCase())
+                const asub = availSubs.find(x => x.display_name.toLowerCase() === sub.toLowerCase())
                 if (asub === undefined) {
                     this.logger.warn(`Will not run on ${sub} because is not modded by, or does not have appropriate permissions to mod with, for this client.`);
                 } else {
@@ -172,54 +263,228 @@ export class App {
         let subSchedule: Manager[] = [];
         // get configs for subs we want to run on and build/validate them
         for (const sub of subsToRun) {
-            let content = undefined;
-            let json = undefined;
+            const manager = new Manager(sub, this.client, this.logger, {dryRun: this.dryRun, sharedModqueue: this.sharedModqueue, wikiLocation: this.wikiLocation, botName: this.botName, maxWorkers: this.maxWorkers});
             try {
-                const wiki = sub.getWikiPage(this.wikiLocation);
-                content = await wiki.content_md;
+                await manager.parseConfiguration('system', true, {suppressNotification: true});
             } catch (err) {
-                this.logger.error(`[${sub.display_name_prefixed}] Could not read wiki configuration. Please ensure the page https://reddit.com${sub.url}wiki/${this.wikiLocation} exists and is readable -- error: ${err.message}`);
-                continue;
-            }
-            try {
-                json = JSON5.parse(content);
-
-            } catch (err) {
-                this.logger.error(`[${sub.display_name_prefixed}] Wiki page contents was not valid -- error: ${err.message}`);
-                continue;
-            }
-            try {
-                subSchedule.push(new Manager(sub, this.client, this.logger, json, {dryRun: this.dryRun}));
-            } catch (err) {
-                this.logger.error(`[${sub.display_name_prefixed}] Config was not valid`, undefined, err);
+                if (!(err instanceof LoggedError)) {
+                    this.logger.error(`Config was not valid:`, {subreddit: sub.display_name_prefixed});
+                    this.logger.error(err, {subreddit: sub.display_name_prefixed});
+                }
             }
+            subSchedule.push(manager);
         }
         this.subManagers = subSchedule;
     }
 
     async heartbeat() {
-        while (true) {
-            await sleep(this.heartbeatInterval * 1000);
-            const heartbeat = `HEARTBEAT -- Reddit API Rate Limit remaining: ${this.client.ratelimitRemaining}`
-            if (this.apiLimitWarning >= this.client.ratelimitRemaining) {
-                this.logger.warn(heartbeat);
-            } else {
+        try {
+            this.heartBeating = true;
+            while (true) {
+                this.nextHeartbeat = dayjs().add(this.heartbeatInterval, 'second');
+                await sleep(this.heartbeatInterval * 1000);
+                const heartbeat = `HEARTBEAT -- API Remaining: ${this.client.ratelimitRemaining} | Usage Rolling Avg: ~${formatNumber(this.apiRollingAvg)}/s | Est Depletion: ${this.apiEstDepletion === undefined ? 'N/A' : this.apiEstDepletion.humanize()} (${formatNumber(this.depletedInSecs, {toFixed: 0})} seconds)`
                 this.logger.info(heartbeat);
+                for (const s of this.subManagers) {
+                    if(s.botState.state === STOPPED && s.botState.causedBy === USER) {
+                        this.logger.debug('Skipping config check/restart on heartbeat due to previously being stopped by user', {subreddit: s.displayLabel});
+                        continue;
+                    }
+                    try {
+                        const newConfig = await s.parseConfiguration();
+                        if(newConfig || (s.queueState.state !== RUNNING && s.queueState.causedBy === SYSTEM))
+                        {
+                            await s.startQueue('system', {reason: newConfig ? 'Config updated on heartbeat triggered reload' : 'Heartbeat detected non-running queue'});
+                        }
+                        if(newConfig || (s.eventsState.state !== RUNNING && s.eventsState.causedBy === SYSTEM))
+                        {
+                            await s.startEvents('system', {reason: newConfig ? 'Config updated on heartbeat triggered reload' : 'Heartbeat detected non-running events'});
+                        }
+                        if(s.botState.state !== RUNNING && s.eventsState.state === RUNNING && s.queueState.state === RUNNING) {
+                            s.botState = {
+                                state: RUNNING,
+                                causedBy: 'system',
+                            }
+                        }
+                    } catch (err) {
+                        this.logger.info('Stopping event polling to prevent activity processing queue from backing up. Will be restarted when config update succeeds.')
+                        await s.stopEvents('system', {reason: 'Invalid config will cause events to pile up in queue. Will be restarted when config update succeeds (next heartbeat).'});
+                        if(!(err instanceof LoggedError)) {
+                            this.logger.error(err, {subreddit: s.displayLabel});
+                        }
+                        if(this.nextHeartbeat !== undefined) {
+                            this.logger.info(`Will retry parsing config on next heartbeat (in ${dayjs.duration(this.nextHeartbeat.diff(dayjs())).humanize()})`, {subreddit: s.displayLabel});
+                        }
+                    }
+                }
+                await this.runModStreams(true);
+            }
+        } catch (err) {
+            this.logger.error('Error occurred during heartbeat', err);
+            throw err;
+        } finally {
+            this.nextHeartbeat = undefined;
+            this.heartBeating = false;
+        }
+    }
+
+    async runModStreams(notify = false) {
+        for(const [k,v] of CacheManager.modStreams) {
+            if(!v.running && v.listeners('item').length > 0) {
+                v.startInterval();
+                this.logger.info(`Starting default ${k.toUpperCase()} mod stream`);
+                if(notify) {
+                    for(const m of this.subManagers) {
+                        if(m.modStreamCallbacks.size > 0) {
+                            m.notificationManager.handle('runStateChanged', `${k.toUpperCase()} Polling Started`, 'Polling was successfully restarted on heartbeat.');
+                        }
+                    }
+                }
             }
         }
     }
 
     async runManagers() {
-
+        if(this.subManagers.every(x => !x.validConfigLoaded)) {
+            this.logger.warn('All managers have invalid configs!');
+        }
         for (const manager of this.subManagers) {
-            manager.handle();
+            if (manager.validConfigLoaded && manager.botState.state !== RUNNING) {
+                await manager.start('system', {reason: 'Caused by application startup'});
+            }
         }
 
-        if (this.heartbeatInterval !== 0) {
+        await this.runModStreams();
+
+        if (this.heartbeatInterval !== 0 && !this.heartBeating) {
             this.heartbeat();
         }
+        this.runApiNanny();
 
         const emitter = new EventEmitter();
         await pEvent(emitter, 'end');
     }
+    
+    async runApiNanny() {
+        while(true) {
+            await sleep(10000);
+            this.nextExpiration = dayjs(this.client.ratelimitExpiration);
+            const nowish = dayjs().add(10, 'second');
+            if(nowish.isAfter(this.nextExpiration)) {
+                // it's possible no api calls are being made because of a hard limit
+                // need to make an api call to update this
+                // @ts-ignore
+                await this.client.getMe();
+                this.nextExpiration = dayjs(this.client.ratelimitExpiration);
+            }
+            const rollingSample = this.apiSample.slice(0, 7)
+            rollingSample.unshift(this.client.ratelimitRemaining);
+            this.apiSample = rollingSample;
+            const diff = this.apiSample.reduceRight((acc: number[], curr, index) => {
+                if(this.apiSample[index + 1] !== undefined) {
+                    const d = Math.abs(curr - this.apiSample[index + 1]);
+                    if(d === 0) {
+                        return [...acc, 0];
+                    }
+                    return [...acc, d/10];
+                }
+                return acc;
+            }, []);
+            this.apiRollingAvg = diff.reduce((acc, curr) => acc + curr,0) / diff.length; // api requests per second
+            this.depletedInSecs = this.client.ratelimitRemaining / this.apiRollingAvg; // number of seconds until current remaining limit is 0
+            this.apiEstDepletion = dayjs.duration({seconds: this.depletedInSecs});
+            this.logger.debug(`API Usage Rolling Avg: ${formatNumber(this.apiRollingAvg)}/s | Est Depletion: ${this.apiEstDepletion.humanize()} (${formatNumber(this.depletedInSecs, {toFixed: 0})} seconds)`);
+
+
+            let hardLimitHit = false;
+            if(typeof this.hardLimit === 'string') {
+                const hardDur = parseDuration(this.hardLimit);
+                hardLimitHit = hardDur.asSeconds() > this.apiEstDepletion.asSeconds();
+            } else {
+                hardLimitHit = this.hardLimit > this.client.ratelimitRemaining;
+            }
+
+            if(hardLimitHit) {
+                if(this.nannyMode === 'hard') {
+                    continue;
+                }
+                this.logger.info(`Detected HARD LIMIT of ${this.hardLimit} remaining`, {leaf: 'Api Nanny'});
+                this.logger.info(`API Remaining: ${this.client.ratelimitRemaining} | Usage Rolling Avg: ${this.apiRollingAvg}/s | Est Depletion: ${this.apiEstDepletion.humanize()} (${formatNumber(this.depletedInSecs, {toFixed: 0})} seconds)`, {leaf: 'Api Nanny'});
+                this.logger.info(`All subreddit event polling has been paused`, {leaf: 'Api Nanny'});
+
+                for(const m of this.subManagers) {
+                    m.pauseEvents('system');
+                    m.notificationManager.handle('runStateChanged', 'Hard Limit Triggered', `Hard Limit of ${this.hardLimit} hit (API Remaining: ${this.client.ratelimitRemaining}). Subreddit event polling has been paused.`, 'system', 'warn');
+                }
+
+                this.nannyMode = 'hard';
+                continue;
+            }
+
+            let softLimitHit = false;
+            if(typeof this.softLimit === 'string') {
+                const softDur = parseDuration(this.softLimit);
+                softLimitHit = softDur.asSeconds() > this.apiEstDepletion.asSeconds();
+            } else {
+                softLimitHit = this.softLimit > this.client.ratelimitRemaining;
+            }
+
+            if(softLimitHit) {
+                if(this.nannyMode === 'soft') {
+                    continue;
+                }
+                this.logger.info(`Detected SOFT LIMIT of ${this.softLimit} remaining`, {leaf: 'Api Nanny'});
+                this.logger.info(`API Remaining: ${this.client.ratelimitRemaining} | Usage Rolling Avg: ${formatNumber(this.apiRollingAvg)}/s | Est Depletion: ${this.apiEstDepletion.humanize()} (${formatNumber(this.depletedInSecs, {toFixed: 0})} seconds)`, {leaf: 'Api Nanny'});
+                this.logger.info('Trying to detect heavy usage subreddits...', {leaf: 'Api Nanny'});
+                let threshold = 0.5;
+                let offenders = this.subManagers.filter(x => {
+                    const combinedPerSec = x.eventsRollingAvg + x.rulesUniqueRollingAvg;
+                    return combinedPerSec > threshold;
+                });
+                if(offenders.length === 0) {
+                    threshold = 0.25;
+                    // reduce threshold
+                    offenders = this.subManagers.filter(x => {
+                        const combinedPerSec = x.eventsRollingAvg + x.rulesUniqueRollingAvg;
+                        return combinedPerSec > threshold;
+                    });
+                }
+
+                if(offenders.length > 0) {
+                    this.logger.info(`Slowing subreddits using >- ${threshold}req/s:`, {leaf: 'Api Nanny'});
+                    for(const m of offenders) {
+                        m.delayBy = 1.5;
+                        m.logger.info(`SLOW MODE (Currently ~${formatNumber(m.eventsRollingAvg + m.rulesUniqueRollingAvg)}req/sec)`, {leaf: 'Api Nanny'});
+                        m.notificationManager.handle('runStateChanged', 'Soft Limit Triggered', `Soft Limit of ${this.softLimit} hit (API Remaining: ${this.client.ratelimitRemaining}). Subreddit queue processing will be slowed to 1.5 seconds per.`, 'system', 'warn');
+                    }
+                } else {
+                    this.logger.info(`Couldn't detect specific offenders, slowing all...`, {leaf: 'Api Nanny'});
+                    for(const m of this.subManagers) {
+                        m.delayBy = 1.5;
+                        m.logger.info(`SLOW MODE (Currently ~${formatNumber(m.eventsRollingAvg + m.rulesUniqueRollingAvg)}req/sec)`, {leaf: 'Api Nanny'});
+                        m.notificationManager.handle('runStateChanged', 'Soft Limit Triggered', `Soft Limit of ${this.softLimit} hit (API Remaining: ${this.client.ratelimitRemaining}). Subreddit queue processing will be slowed to 1.5 seconds per.`, 'system', 'warn');
+                    }
+                }
+                this.nannyMode = 'soft';
+                continue;
+            }
+
+            if(this.nannyMode !== undefined) {
+                this.logger.info('Turning off due to better conditions...', {leaf: 'Api Nanny'});
+                for(const m of this.subManagers) {
+                    if(m.delayBy !== undefined) {
+                        m.delayBy = undefined;
+                        m.notificationManager.handle('runStateChanged', 'Normal Processing Resumed', 'Slow Mode has been turned off due to better API conditions', 'system');
+                    }
+                    if(m.queueState.state === PAUSED && m.queueState.causedBy === SYSTEM) {
+                        m.startQueue('system', {reason: 'API Nanny has been turned off due to better API conditions'});
+                    }
+                    if(m.eventsState.state === PAUSED && m.eventsState.causedBy === SYSTEM) {
+                        await m.startEvents('system', {reason: 'API Nanny has been turned off due to better API conditions'});
+                    }
+                }
+                this.nannyMode = undefined;
+            }
+        }
+    }
 }

src/Author/Author.ts

@@ -0,0 +1,129 @@
+import {DurationComparor, UserNoteCriteria} from "../Rule";
+import {CompareValue, CompareValueOrPercent} from "../Common/interfaces";
+
+/**
+ * If present then these Author criteria are checked before running the rule. If criteria fails then the rule is skipped.
+ * @examples [{"include": [{"flairText": ["Contributor","Veteran"]}, {"isMod": true}]}]
+ * */
+export interface AuthorOptions {
+    /**
+     * Will "pass" if any set of AuthorCriteria passes
+     * */
+    include?: AuthorCriteria[];
+    /**
+     * Only runs if `include` is not present. Will "pass" if any of set of the AuthorCriteria **does not** pass
+     * */
+    exclude?: AuthorCriteria[];
+}
+
+/**
+ * Criteria with which to test against the author of an Activity. The outcome of the test is based on:
+ *
+ * 1. All present properties passing and
+ * 2. If a property is a list then any value from the list matching
+ *
+ * @minProperties 1
+ * @additionalProperties false
+ * @examples [{"flairText": ["Contributor","Veteran"], "isMod": true, "name": ["FoxxMD", "AnotherUser"] }]
+ * */
+export interface AuthorCriteria {
+    /**
+     * A list of reddit usernames (case-insensitive) to match against. Do not include the "u/" prefix
+     *
+     *  EX to match against /u/FoxxMD and /u/AnotherUser use ["FoxxMD","AnotherUser"]
+     * @examples ["FoxxMD","AnotherUser"]
+     * */
+    name?: string[],
+    /**
+     * A list of (user) flair css class values from the subreddit to match against
+     * @examples ["red"]
+     * */
+    flairCssClass?: string[],
+    /**
+     * A list of (user) flair text values from the subreddit to match against
+     * @examples ["Approved"]
+     * */
+    flairText?: string[],
+    /**
+     * Is the author a moderator?
+     * */
+    isMod?: boolean,
+    /**
+     * A list of UserNote properties to check against the User Notes attached to this Author in this Subreddit (must have Toolbox enabled and used User Notes at least once)
+     * */
+    userNotes?: UserNoteCriteria[]
+
+    /**
+     * Test the age of the Author's account (when it was created) against this comparison
+     *
+     * The syntax is `(< OR > OR <= OR >=) <number> <unit>`
+     *
+     * * EX `> 100 days` => Passes if Author's account is older than 100 days
+     * * EX `<= 2 months` => Passes if Author's account is younger than or equal to 2 months
+     *
+     * Unit must be one of [DayJS Duration units](https://day.js.org/docs/en/durations/creating)
+     *
+     * [See] https://regexr.com/609n8 for example
+     *
+     * @pattern ^\s*(?<opStr>>|>=|<|<=)\s*(?<time>\d+)\s*(?<unit>days?|weeks?|months?|years?|hours?|minutes?|seconds?|milliseconds?)\s*$
+     * */
+    age?: DurationComparor
+
+    /**
+     * A string containing a comparison operator and a value to compare link karma against
+     *
+     * The syntax is `(< OR > OR <= OR >=) <number>[percent sign]`
+     *
+     * * EX `> 100`  => greater than 100 link karma
+     * * EX `<= 75%` => link karma is less than or equal to 75% of **all karma**
+     *
+     * @pattern ^\s*(>|>=|<|<=)\s*(\d+)\s*(%?)(.*)$
+     * */
+    linkKarma?: CompareValueOrPercent
+
+    /**
+     * A string containing a comparison operator and a value to compare karma against
+     *
+     * The syntax is `(< OR > OR <= OR >=) <number>[percent sign]`
+     *
+     * * EX `> 100`  => greater than 100 comment karma
+     * * EX `<= 75%` => comment karma is less than or equal to 75% of **all karma**
+     *
+     * @pattern ^\s*(>|>=|<|<=)\s*(\d+)\s*(%?)(.*)$
+     * */
+    commentKarma?: CompareValueOrPercent
+
+    totalKarma?: CompareValue
+
+    /**
+     * Does Author's account have a verified email?
+     * */
+    verified?: boolean
+}
+
+export class Author implements AuthorCriteria {
+    name?: string[];
+    flairCssClass?: string[];
+    flairText?: string[];
+    isMod?: boolean;
+    userNotes?: UserNoteCriteria[];
+    age?: string;
+    commentKarma?: string;
+    linkKarma?: string;
+    totalKarma?: string;
+    verified?: boolean;
+
+    constructor(options: AuthorCriteria) {
+        this.name = options.name;
+        this.flairCssClass = options.flairCssClass;
+        this.flairText = options.flairText;
+        this.isMod = options.isMod;
+        this.userNotes = options.userNotes;
+        this.age = options.age;
+        this.commentKarma = options.commentKarma;
+        this.linkKarma = options.linkKarma;
+        this.totalKarma = options.totalKarma;
+    }
+}
+
+export default Author;

src/Check/CommentCheck.js

@@ -1,8 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CommentCheck = void 0;
-const index_1 = require("./index");
-class CommentCheck extends index_1.Check {
-}
-exports.CommentCheck = CommentCheck;
-//# sourceMappingURL=CommentCheck.js.map

src/Check/CommentCheck.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"CommentCheck.js","sourceRoot":"","sources":["CommentCheck.ts"],"names":[],"mappings":";;;AAAA,mCAA8B;AAE9B,MAAa,YAAa,SAAQ,aAAK;CAEtC;AAFD,oCAEC"}

src/Check/CommentCheck.ts

@@ -1,5 +1,54 @@
-import {Check} from "./index";
+import {Check, CheckOptions, userResultCacheDefault, UserResultCacheOptions} from "./index";
+import {CommentState} from "../Common/interfaces";
+import {Submission, Comment} from "snoowrap/dist/objects";
+
+export interface CommentCheckOptions extends CheckOptions {
+    cacheUserResult?: UserResultCacheOptions;
+}
 
 export class CommentCheck extends Check {
+    itemIs: CommentState[];
 
+    cacheUserResult: Required<UserResultCacheOptions>;
+
+    constructor(options: CommentCheckOptions) {
+        super(options);
+        const {
+            itemIs = [],
+            cacheUserResult = {},
+        } = options;
+
+        this.cacheUserResult = {
+            ...userResultCacheDefault,
+            ...cacheUserResult
+        }
+
+        this.itemIs = itemIs;
+        this.logSummary();
+    }
+
+    logSummary() {
+        super.logSummary('comment');
+    }
+
+    async getCacheResult(item: Submission | Comment): Promise<boolean | undefined> {
+        if (this.cacheUserResult.enable) {
+            return await this.resources.getCommentCheckCacheResult(item as Comment, {
+                name: this.name,
+                authorIs: this.authorIs,
+                itemIs: this.itemIs
+            })
+        }
+        return undefined;
+    }
+
+    async setCacheResult(item: Submission | Comment, result: boolean): Promise<void> {
+        if (this.cacheUserResult.enable) {
+            await this.resources.setCommentCheckCacheResult(item as Comment, {
+                name: this.name,
+                authorIs: this.authorIs,
+                itemIs: this.itemIs
+            }, result, this.cacheUserResult.ttl)
+        }
+    }
 }

src/Check/SubmissionCheck.js

@@ -1,8 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SubmissionCheck = void 0;
-const index_1 = require("./index");
-class SubmissionCheck extends index_1.Check {
-}
-exports.SubmissionCheck = SubmissionCheck;
-//# sourceMappingURL=SubmissionCheck.js.map

src/Check/SubmissionCheck.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"SubmissionCheck.js","sourceRoot":"","sources":["SubmissionCheck.ts"],"names":[],"mappings":";;;AACA,mCAA8B;AAE9B,MAAa,eAAgB,SAAQ,aAAK;CAEzC;AAFD,0CAEC"}

src/Check/SubmissionCheck.ts

@@ -1,6 +1,25 @@
-
-import {Check} from "./index";
+import {Check, CheckOptions} from "./index";
+import {SubmissionState} from "../Common/interfaces";
+import {Submission, Comment} from "snoowrap/dist/objects";
 
 export class SubmissionCheck extends Check {
+    itemIs: SubmissionState[];
 
+    constructor(options: CheckOptions) {
+        super(options);
+        const {itemIs = []} = options;
+        this.itemIs = itemIs;
+        this.logSummary();
+    }
+
+    logSummary() {
+        super.logSummary('submission');
+    }
+
+    async getCacheResult(item: Submission | Comment) {
+        return undefined;
+    }
+
+    async setCacheResult(item: Submission | Comment, result: boolean) {
+    }
 }

src/Check/index.ts

@@ -1,45 +1,89 @@
 import {RuleSet, IRuleSet, RuleSetJson, RuleSetObjectJson} from "../Rule/RuleSet";
-import {IRule,Rule, RuleJSONConfig, RuleResult} from "../Rule";
+import {IRule, isRuleSetResult, Rule, RuleJSONConfig, RuleResult, RuleSetResult} from "../Rule";
 import Action, {ActionConfig, ActionJson} from "../Action";
 import {Logger} from "winston";
 import {Comment, Submission} from "snoowrap";
 import {actionFactory} from "../Action/ActionFactory";
 import {ruleFactory} from "../Rule/RuleFactory";
-import {createAjvFactory, mergeArr, ruleNamesFromResults} from "../util";
-import {JoinCondition, JoinOperands} from "../Common/interfaces";
+import {
+    boolToString,
+    createAjvFactory,
+    FAIL,
+    mergeArr,
+    PASS,
+    resultsSummary,
+    ruleNamesFromResults,
+    truncateStringToLength
+} from "../util";
+import {
+    ChecksActivityState,
+    CommentState,
+    JoinCondition,
+    JoinOperands,
+    SubmissionState,
+    TypedActivityStates
+} from "../Common/interfaces";
 import * as RuleSchema from '../Schema/Rule.json';
 import * as RuleSetSchema from '../Schema/RuleSet.json';
 import * as ActionSchema from '../Schema/Action.json';
-import Ajv from 'ajv';
 import {ActionObjectJson, RuleJson, RuleObjectJson, ActionJson as ActionTypeJson} from "../Common/types";
+import ResourceManager, {SubredditResources} from "../Subreddit/SubredditResources";
+import {Author, AuthorCriteria, AuthorOptions} from "../Author/Author";
 
-export class Check implements ICheck {
+const checkLogName = truncateStringToLength(25);
+
+export abstract class Check implements ICheck {
     actions: Action[] = [];
     description?: string;
     name: string;
+    enabled: boolean;
     condition: JoinOperands;
     rules: Array<RuleSet | Rule> = [];
     logger: Logger;
+    itemIs: TypedActivityStates;
+    authorIs: {
+        include: AuthorCriteria[],
+        exclude: AuthorCriteria[]
+    };
     dryRun?: boolean;
+    notifyOnTrigger: boolean;
+    resources: SubredditResources;
 
     constructor(options: CheckOptions) {
         const {
+            enable = true,
             name,
             description,
             condition = 'AND',
             rules = [],
             actions = [],
+            notifyOnTrigger = false,
             subredditName,
+            itemIs = [],
+            authorIs: {
+                include = [],
+                exclude = [],
+            } = {},
             dryRun,
         } = options;
 
-        this.logger = options.logger.child({labels: [`Check ${name}`]}, mergeArr);
+        this.enabled = enable;
+
+        this.logger = options.logger.child({labels: [`CHK ${checkLogName(name)}`]}, mergeArr);
 
         const ajv = createAjvFactory(this.logger);
 
+        this.resources = ResourceManager.get(subredditName) as SubredditResources;
+
         this.name = name;
         this.description = description;
+        this.notifyOnTrigger = notifyOnTrigger;
         this.condition = condition;
+        this.itemIs = itemIs;
+        this.authorIs = {
+            exclude: exclude.map(x => new Author(x)),
+            include: include.map(x => new Author(x)),
+        }
         this.dryRun = dryRun;
         for (const r of rules) {
             if (r instanceof Rule || r instanceof RuleSet) {
@@ -76,7 +120,10 @@ export class Check implements ICheck {
                 let valid = ajv.validate(ActionSchema, a);
                 if (valid) {
                     const aj = a as ActionJson;
-                    this.actions.push(actionFactory({...aj, dryRun: this.dryRun || aj.dryRun}, this.logger, subredditName));
+                    this.actions.push(actionFactory({
+                        ...aj,
+                        dryRun: this.dryRun || aj.dryRun
+                    }, this.logger, subredditName));
                     // @ts-ignore
                     a.logger = this.logger;
                 } else {
@@ -84,65 +131,198 @@ export class Check implements ICheck {
                 }
             }
         }
-
-
     }
 
-    async run(item: Submission | Comment, existingResults: RuleResult[] = []): Promise<[boolean, RuleResult[]]> {
-        let allResults: RuleResult[] = [];
-        let runOne = false;
+    logSummary(type: string) {
+        const runStats = [];
+        const ruleSetCount = this.rules.reduce((x, r) => r instanceof RuleSet ? x + 1 : x, 0);
+        const rulesInSetsCount = this.rules.reduce((x, r) => r instanceof RuleSet ? x + r.rules.length : x, 0);
+        if (ruleSetCount > 0) {
+            runStats.push(`${ruleSetCount} Rule Sets (${rulesInSetsCount} Rules)`);
+        }
+        const topRuleCount = this.rules.reduce((x, r) => r instanceof Rule ? x + 1 : x, 0);
+        if (topRuleCount > 0) {
+            runStats.push(`${topRuleCount} Top-Level Rules`);
+        }
+        runStats.push(`${this.actions.length} Actions`);
+        // not sure if this should be info or verbose
+        this.logger.info(`=${this.enabled ? 'Enabled' : 'Disabled'}= ${type.toUpperCase()} (${this.condition})${this.notifyOnTrigger ? ' ||Notify on Trigger|| ' : ''} => ${runStats.join(' | ')}${this.description !== undefined ? ` => ${this.description}` : ''}`);
+        if (this.rules.length === 0 && this.itemIs.length === 0 && this.authorIs.exclude.length === 0 && this.authorIs.include.length === 0) {
+            this.logger.warn('No rules, item tests, or author test found -- this check will ALWAYS PASS!');
+        }
+        let ruleSetIndex = 1;
         for (const r of this.rules) {
-            const combinedResults = [...existingResults, ...allResults];
-            const [passed, results] = await r.run(item, combinedResults);
-            allResults = allResults.concat(results);
-            if (passed === null) {
+            if (r instanceof RuleSet) {
+                for (const ru of r.rules) {
+                    this.logger.verbose(`(Rule Set ${ruleSetIndex} ${r.condition}) => ${ru.getRuleUniqueName()}`);
+                }
+                ruleSetIndex++;
+            } else {
+                this.logger.verbose(`(Rule) => ${r.getRuleUniqueName()}`);
+            }
+        }
+        for (const a of this.actions) {
+            this.logger.verbose(`(Action) => ${a.getActionUniqueName()}`);
+        }
+    }
+
+    abstract getCacheResult(item: Submission | Comment) : Promise<boolean | undefined>;
+    abstract setCacheResult(item: Submission | Comment, result: boolean): void;
+
+    async runRules(item: Submission | Comment, existingResults: RuleResult[] = []): Promise<[boolean, RuleResult[]]> {
+        try {
+            let allRuleResults: RuleResult[] = [];
+            let allResults: (RuleResult | RuleSetResult)[] = [];
+
+            // check cache results
+            const cacheResult = await this.getCacheResult(item);
+            if(cacheResult !== undefined) {
+                this.logger.verbose(`Skipping rules run because result was found in cache, Check Triggered Result: ${cacheResult}`);
+                return [cacheResult, allRuleResults];
+            }
+
+            const itemPass = await this.resources.testItemCriteria(item, this.itemIs);
+            if (!itemPass) {
+                this.logger.verbose(`${FAIL} => Item did not pass 'itemIs' test`);
+                return [false, allRuleResults];
+            }
+            let authorPass = null;
+            if (this.authorIs.include !== undefined && this.authorIs.include.length > 0) {
+                for (const auth of this.authorIs.include) {
+                    if (await this.resources.testAuthorCriteria(item, auth)) {
+                        authorPass = true;
+                        break;
+                    }
+                }
+                if (!authorPass) {
+                    this.logger.verbose(`${FAIL} => Inclusive author criteria not matched`);
+                    return Promise.resolve([false, allRuleResults]);
+                }
+            }
+            if (authorPass === null && this.authorIs.exclude !== undefined && this.authorIs.exclude.length > 0) {
+                for (const auth of this.authorIs.exclude) {
+                    if (await this.resources.testAuthorCriteria(item, auth, false)) {
+                        authorPass = true;
+                        break;
+                    }
+                }
+                if (!authorPass) {
+                    this.logger.verbose(`${FAIL} =>  Exclusive author criteria not matched`);
+                    return Promise.resolve([false, allRuleResults]);
+                }
+            }
+
+            if (this.rules.length === 0) {
+                this.logger.info(`${PASS} => No rules to run, check auto-passes`);
+                return [true, allRuleResults];
+            }
+
+            let runOne = false;
+            for (const r of this.rules) {
+                //let results: RuleResult | RuleSetResult;
+                const combinedResults = [...existingResults, ...allRuleResults];
+                const [passed, results] = await r.run(item, combinedResults);
+                if (isRuleSetResult(results)) {
+                    allRuleResults = allRuleResults.concat(results.results);
+                } else {
+                    allRuleResults = allRuleResults.concat(results as RuleResult);
+                }
+                allResults.push(results);
+                if (passed === null) {
+                    continue;
+                }
+                runOne = true;
+                if (passed) {
+                    if (this.condition === 'OR') {
+                        this.logger.info(`${PASS} => Rules: ${resultsSummary(allResults, this.condition)}`);
+                        return [true, allRuleResults];
+                    }
+                } else if (this.condition === 'AND') {
+                    this.logger.verbose(`${FAIL} => Rules: ${resultsSummary(allResults, this.condition)}`);
+                    return [false, allRuleResults];
+                }
+            }
+            if (!runOne) {
+                this.logger.verbose(`${FAIL} => All Rules skipped because of Author checks or itemIs tests`);
+                return [false, allRuleResults];
+            } else if (this.condition === 'OR') {
+                // if OR and did not return already then none passed
+                this.logger.verbose(`${FAIL} => Rules: ${resultsSummary(allResults, this.condition)}`);
+                return [false, allRuleResults];
+            }
+            // otherwise AND and did not return already so all passed
+            this.logger.info(`${PASS} => Rules: ${resultsSummary(allResults, this.condition)}`);
+            return [true, allRuleResults];
+        } catch (e) {
+            e.logged = true;
+            this.logger.warn(`Running rules failed due to uncaught exception`, e);
+            throw e;
+        }
+    }
+
+    async runActions(item: Submission | Comment, ruleResults: RuleResult[], runtimeDryrun?: boolean): Promise<Action[]> {
+        const dr = runtimeDryrun || this.dryRun;
+        this.logger.debug(`${dr ? 'DRYRUN - ' : ''}Running Actions`);
+        const runActions: Action[] = [];
+        for (const a of this.actions) {
+            if(!a.enabled) {
+                this.logger.info(`Action ${a.getActionUniqueName()} not run because it is not enabled.`);
                 continue;
             }
-            runOne = true;
-            if (passed) {
-                if (this.condition === 'OR') {
-                    this.logger.info(`✔️ => Rules (OR): ${ruleNamesFromResults(allResults)}`);
-                    return [true, allResults];
-                }
-            } else if (this.condition === 'AND') {
-                this.logger.info(`❌ => Rules (AND): ${ruleNamesFromResults(allResults)}`);
-                return [false, allResults];
+            try {
+                await a.handle(item, ruleResults, runtimeDryrun);
+                runActions.push(a);
+            } catch (err) {
+                this.logger.error(`Action ${a.getActionUniqueName()} encountered an error while running`, err);
             }
         }
-        if (!runOne) {
-            this.logger.info('❌ => All Rules skipped because of Author checks');
-            return [false, allResults];
-        }
-        this.logger.info(`✔️ => Rules (AND) : ${ruleNamesFromResults(allResults)}`);
-        return [true, allResults];
-    }
-
-    async runActions(item: Submission | Comment, ruleResults: RuleResult[]): Promise<void> {
-        this.logger.debug(`${this.dryRun ? 'DRYRUN - ' : ''}Running Actions`);
-        for (const a of this.actions) {
-            await a.handle(item, ruleResults);
-        }
-        this.logger.info(`${this.dryRun ? 'DRYRUN - ' : ''}Ran Actions`);
+        this.logger.info(`${dr ? 'DRYRUN - ' : ''}Ran Actions: ${runActions.map(x => x.getActionUniqueName()).join(' | ')}`);
+        return runActions;
     }
 }
 
-export interface ICheck extends JoinCondition {
+export interface ICheck extends JoinCondition, ChecksActivityState {
     /**
      * Friendly name for this Check EX "crosspostSpamCheck"
      *
      * Can only contain letters, numbers, underscore, spaces, and dashes
      *
      * @pattern ^[a-zA-Z]([\w -]*[\w])?$
+     * @examples ["myNewCheck"]
      * */
     name: string,
+    /**
+     * @examples ["A short description of what this check looks for and actions it performs"]
+     * */
     description?: string,
 
     /**
      * Use this option to override the `dryRun` setting for all of its `Actions`
-     *
-     * @default undefined
+     * @examples [false, true]
      * */
     dryRun?: boolean;
+
+    /**
+     * A list of criteria to test the state of the `Activity` against before running the check.
+     *
+     * If any set of criteria passes the Check will be run. If the criteria fails then the Check will fail.
+     *
+     * * @examples [[{"over_18": true, "removed': false}]]
+     * */
+    itemIs?: TypedActivityStates
+
+    /**
+     * If present then these Author criteria are checked before running the Check. If criteria fails then the Check will fail.
+     * */
+    authorIs?: AuthorOptions
+
+    /**
+     * Should this check be run by the bot?
+     *
+     * @default true
+     * @examples [true]
+     * */
+    enable?: boolean,
 }
 
 export interface CheckOptions extends ICheck {
@@ -150,31 +330,91 @@ export interface CheckOptions extends ICheck {
     actions: ActionConfig[]
     logger: Logger
     subredditName: string
+    notifyOnTrigger?: boolean
 }
 
 export interface CheckJson extends ICheck {
     /**
      * The type of event (new submission or new comment) this check should be run against
+     * @examples ["submission", "comment"]
      */
     kind: 'submission' | 'comment'
     /**
-     * A list of Rules to run. If `Rule` objects are triggered based on `condition` then `Actions` will be performed.
+     * A list of Rules to run.
      *
-     * Can be `Rule`, `RuleSet`, or the `name` of any **named** `Rule` in your subreddit's configuration
-     * @minItems 1
+     * If `Rule` objects are triggered based on `condition` then `actions` will be performed.
+     *
+     * Can be `Rule`, `RuleSet`, or the `name` of any **named** `Rule` in your subreddit's configuration.
+     *
+     * **If `rules` is an empty array or not present then `actions` are performed immediately.**
      * */
-    rules: Array<RuleSetJson | RuleJson>
+    rules?: Array<RuleSetJson | RuleJson>
     /**
      * The `Actions` to run after the check is successfully triggered. ALL `Actions` will run in the order they are listed
      *
      *  Can be `Action` or the `name` of any **named** `Action` in your subreddit's configuration
      *
      * @minItems 1
+     * @examples [[{"kind": "comment", "content": "this is the content of the comment", "distinguish": true}, {"kind": "lock"}]]
      * */
     actions: Array<ActionTypeJson>
+
+    /**
+     * If notifications are configured and this is `true` then an `eventActioned` event will be sent when this check is triggered.
+     *
+     * @default false
+     * */
+    notifyOnTrigger?: boolean,
 }
 
-export interface CheckStructuredJson extends CheckJson {
+export interface SubmissionCheckJson extends CheckJson {
+    kind: 'submission'
+    itemIs?: SubmissionState[]
+}
+
+/**
+ * Cache the result of this check based on the comment author and the submission id
+ *
+ * This is useful in this type of scenario:
+ *
+ * 1. This check is configured to run on comments for specific submissions with high volume activity
+ * 2. The rules being run are not dependent on the content of the comment
+ * 3. The rule results are not likely to change while cache is valid
+ * */
+export interface UserResultCacheOptions {
+    enable?: boolean,
+    /**
+     * The amount of time, in seconds, to cache this result
+     *
+     * @default 60
+     * @examples [60]
+     * */
+    ttl?: number,
+}
+
+export const userResultCacheDefault: Required<UserResultCacheOptions> = {
+    enable: false,
+    ttl: 60,
+}
+
+export interface CommentCheckJson extends CheckJson {
+    kind: 'comment'
+    itemIs?: CommentState[]
+    cacheUserResult?:  UserResultCacheOptions
+}
+
+export type CheckStructuredJson = SubmissionCheckStructuredJson | CommentCheckStructuredJson;
+// export interface CheckStructuredJson extends CheckJson {
+//     rules: Array<RuleSetObjectJson | RuleObjectJson>
+//     actions: Array<ActionObjectJson>
+// }
+
+export interface SubmissionCheckStructuredJson extends SubmissionCheckJson {
+    rules: Array<RuleSetObjectJson | RuleObjectJson>
+    actions: Array<ActionObjectJson>
+}
+
+export interface CommentCheckStructuredJson extends CommentCheckJson {
     rules: Array<RuleSetObjectJson | RuleObjectJson>
     actions: Array<ActionObjectJson>
 }

src/Common/defaults.ts

@@ -0,0 +1,2 @@
+export const cacheOptDefaults = {ttl: 60, max: 500, checkPeriod: 600};
+export const cacheTTLDefaults = {authorTTL: 60, userNotesTTL: 300, wikiTTL: 300, submissionTTL: 60, commentTTL: 60, filterCriteriaTTL: 60};

src/Common/types.ts

@@ -1,16 +1,21 @@
 import {RecentActivityRuleJSONConfig} from "../Rule/RecentActivityRule";
-import {RepeatActivityJSONConfig} from "../Rule/SubmissionRule/RepeatActivityRule";
+import {RepeatActivityJSONConfig} from "../Rule/RepeatActivityRule";
 import {AuthorRuleJSONConfig} from "../Rule/AuthorRule";
-import {AttributionJSONConfig} from "../Rule/SubmissionRule/AttributionRule";
+import {AttributionJSONConfig} from "../Rule/AttributionRule";
 import {FlairActionJson} from "../Action/SubmissionAction/FlairAction";
 import {CommentActionJson} from "../Action/CommentAction";
 import {ReportActionJson} from "../Action/ReportAction";
 import {LockActionJson} from "../Action/LockAction";
 import {RemoveActionJson} from "../Action/RemoveAction";
 import {HistoryJSONConfig} from "../Rule/HistoryRule";
+import {UserNoteActionJson} from "../Action/UserNoteAction";
+import {ApproveActionJson} from "../Action/ApproveAction";
+import {BanActionJson} from "../Action/BanAction";
+import {RegexRuleJSONConfig} from "../Rule/RegexRule";
+import {MessageActionJson} from "../Action/MessageAction";
 
-export type RuleJson = RecentActivityRuleJSONConfig | RepeatActivityJSONConfig | AuthorRuleJSONConfig | AttributionJSONConfig | HistoryJSONConfig | string;
+export type RuleJson = RecentActivityRuleJSONConfig | RepeatActivityJSONConfig | AuthorRuleJSONConfig | AttributionJSONConfig | HistoryJSONConfig | RegexRuleJSONConfig | string;
 export type RuleObjectJson = Exclude<RuleJson, string>
 
-export type ActionJson = FlairActionJson | CommentActionJson | ReportActionJson | LockActionJson | RemoveActionJson | string;
+export type ActionJson = CommentActionJson | FlairActionJson | ReportActionJson | LockActionJson | RemoveActionJson | ApproveActionJson | BanActionJson | UserNoteActionJson | MessageActionJson | string;
 export type ActionObjectJson = Exclude<ActionJson, string>;

src/ConfigBuilder.ts

@@ -1,23 +1,98 @@
 import {Logger} from "winston";
-import {createAjvFactory, mergeArr, normalizeName} from "./util";
+import {
+    buildCacheOptionsFromProvider,
+    createAjvFactory,
+    mergeArr,
+    normalizeName,
+    overwriteMerge,
+    parseBool, randomId,
+    readJson,
+    removeUndefinedKeys
+} from "./util";
 import {CommentCheck} from "./Check/CommentCheck";
 import {SubmissionCheck} from "./Check/SubmissionCheck";
 
-import Ajv from 'ajv';
-import * as schema from './Schema/App.json';
+import Ajv, {Schema} from 'ajv';
+import * as appSchema from './Schema/App.json';
+import * as operatorSchema from './Schema/OperatorConfig.json';
 import {JSONConfig} from "./JsonConfig";
 import LoggedError from "./Utils/LoggedError";
 import {CheckStructuredJson} from "./Check";
-import {ManagerOptions} from "./Common/interfaces";
+import {
+    DEFAULT_POLLING_INTERVAL,
+    DEFAULT_POLLING_LIMIT,
+    OperatorJsonConfig,
+    OperatorConfig,
+    PollingOptions,
+    PollingOptionsStrong,
+    PollOn, StrongCache, CacheProvider, CacheOptions
+} from "./Common/interfaces";
 import {isRuleSetJSON, RuleSetJson, RuleSetObjectJson} from "./Rule/RuleSet";
 import deepEqual from "fast-deep-equal";
 import {ActionJson, ActionObjectJson, RuleJson, RuleObjectJson} from "./Common/types";
 import {isActionJson} from "./Action";
+import {getLogger} from "./Utils/loggerFactory";
+import {GetEnvVars} from 'env-cmd';
+import {operatorConfig} from "./Utils/CommandConfig";
+import merge from 'deepmerge';
+import * as process from "process";
+import {cacheOptDefaults, cacheTTLDefaults} from "./Common/defaults";
 
 export interface ConfigBuilderOptions {
     logger: Logger,
 }
 
+export const validateJson = (config: object, schema: Schema, logger: Logger): any => {
+    const ajv = createAjvFactory(logger);
+    const valid = ajv.validate(schema, config);
+    if (valid) {
+        return config;
+    } else {
+        logger.error('Json config was not valid. Please use schema to check validity.', {leaf: 'Config'});
+        if (Array.isArray(ajv.errors)) {
+            for (const err of ajv.errors) {
+                let parts = [
+                    `At: ${err.dataPath}`,
+                ];
+                let data;
+                if (typeof err.data === 'string') {
+                    data = err.data;
+                } else if (err.data !== null && typeof err.data === 'object' && (err.data as any).name !== undefined) {
+                    data = `Object named '${(err.data as any).name}'`;
+                }
+                if (data !== undefined) {
+                    parts.push(`Data: ${data}`);
+                }
+                let suffix = '';
+                // @ts-ignore
+                if (err.params.allowedValues !== undefined) {
+                    // @ts-ignore
+                    suffix = err.params.allowedValues.join(', ');
+                    suffix = ` [${suffix}]`;
+                }
+                parts.push(`${err.keyword}: ${err.schemaPath} => ${err.message}${suffix}`);
+
+                // if we have a reference in the description parse it out so we can log it here for context
+                if (err.parentSchema !== undefined && err.parentSchema.description !== undefined) {
+                    const desc = err.parentSchema.description as string;
+                    const seeIndex = desc.indexOf('[See]');
+                    if (seeIndex !== -1) {
+                        let newLineIndex: number | undefined = desc.indexOf('\n', seeIndex);
+                        if (newLineIndex === -1) {
+                            newLineIndex = undefined;
+                        }
+                        const seeFragment = desc.slice(seeIndex + 5, newLineIndex);
+                        parts.push(`See:${seeFragment}`);
+                    }
+                }
+
+                logger.error(`Schema Error:\r\n${parts.join('\r\n')}`, {leaf: 'Config'});
+            }
+        }
+        throw new LoggedError('Config schema validity failure');
+    }
+}
+
 export class ConfigBuilder {
     configLogger: Logger;
     logger: Logger;
@@ -29,26 +104,8 @@ export class ConfigBuilder {
     }
 
     validateJson(config: object): JSONConfig {
-        const ajv = createAjvFactory(this.logger);
-        const valid = ajv.validate(schema, config);
-        if (valid) {
-            return config as JSONConfig;
-        } else {
-            this.configLogger.error('Json config was not valid. Please use schema to check validity.');
-            if (Array.isArray(ajv.errors)) {
-                for (const err of ajv.errors) {
-                    let suffix = '';
-                    // @ts-ignore
-                    if (err.params.allowedValues !== undefined) {
-                        // @ts-ignore
-                        suffix = err.params.allowedValues.join(', ');
-                        suffix = ` [${suffix}]`;
-                    }
-                    this.configLogger.error(`${err.keyword}: ${err.schemaPath} => ${err.message}${suffix}`);
-                }
-            }
-            throw new LoggedError();
-        }
+        const validConfig = validateJson(config, appSchema, this.logger);
+        return validConfig as JSONConfig;
     }
 
     parseToStructured(config: JSONConfig): CheckStructuredJson[] {
@@ -56,13 +113,15 @@ export class ConfigBuilder {
         let namedActions: Map<string, ActionObjectJson> = new Map();
         const {checks = []} = config;
         for (const c of checks) {
-            namedRules = extractNamedRules(c.rules, namedRules);
+            const {rules = []} = c;
+            namedRules = extractNamedRules(rules, namedRules);
             namedActions = extractNamedActions(c.actions, namedActions);
         }
 
         const structuredChecks: CheckStructuredJson[] = [];
         for (const c of checks) {
-            const strongRules = insertNamedRules(c.rules, namedRules);
+            const {rules = []} = c;
+            const strongRules = insertNamedRules(rules, namedRules);
             const strongActions = insertNamedActions(c.actions, namedActions);
             const strongCheck = {...c, rules: strongRules, actions: strongActions} as CheckStructuredJson;
             structuredChecks.push(strongCheck);
@@ -72,6 +131,24 @@ export class ConfigBuilder {
     }
 }
 
+export const buildPollingOptions = (values: (string | PollingOptions)[]): PollingOptionsStrong[] => {
+    let opts: PollingOptionsStrong[] = [];
+    for (const v of values) {
+        if (typeof v === 'string') {
+            opts.push({pollOn: v as PollOn, interval: DEFAULT_POLLING_INTERVAL, limit: DEFAULT_POLLING_LIMIT});
+        } else {
+            const {
+                pollOn: p,
+                interval = DEFAULT_POLLING_INTERVAL,
+                limit = DEFAULT_POLLING_LIMIT,
+                delayUntil,
+            } = v;
+            opts.push({pollOn: p as PollOn, interval, limit, delayUntil});
+        }
+    }
+    return opts;
+}
+
 export const extractNamedRules = (rules: Array<RuleSetJson | RuleJson>, namedRules: Map<string, RuleObjectJson> = new Map()): Map<string, RuleObjectJson> => {
     //const namedRules = new Map();
     for (const r of rules) {
@@ -168,3 +245,358 @@ export const insertNamedActions = (actions: Array<ActionJson>, namedActions: Map
 
     return strongActions;
 }
+
+export const parseOpConfigFromArgs = (args: any): OperatorJsonConfig => {
+    const {
+        subreddits,
+        clientId,
+        clientSecret,
+        accessToken,
+        refreshToken,
+        redirectUri,
+        wikiConfig,
+        dryRun,
+        heartbeat,
+        softLimit,
+        hardLimit,
+        authorTTL,
+        operator,
+        operatorDisplay,
+        snooProxy,
+        snooDebug,
+        sharedMod,
+        logLevel,
+        logDir,
+        port,
+        sessionSecret,
+        caching,
+        web
+    } = args || {};
+
+    const data = {
+        operator: {
+            name: operator,
+            display: operatorDisplay
+        },
+        credentials: {
+            clientId,
+            clientSecret,
+            accessToken,
+            refreshToken,
+            redirectUri,
+        },
+        subreddits: {
+            names: subreddits,
+            wikiConfig,
+            heartbeatInterval: heartbeat,
+            dryRun
+        },
+        logging: {
+            level: logLevel,
+            path: logDir === true ? `${process.cwd()}/logs` : undefined,
+        },
+        snoowrap: {
+            proxy: snooProxy,
+            debug: snooDebug,
+        },
+        web: {
+            enabled: web,
+            port,
+            session: {
+                secret: sessionSecret
+            }
+        },
+        polling: {
+            sharedMod,
+        },
+        caching: {
+            provider: caching,
+            authorTTL
+        },
+        api: {
+            softLimit,
+            hardLimit
+        }
+    }
+
+    return removeUndefinedKeys(data) as OperatorJsonConfig;
+}
+
+const parseListFromEnv = (val: string|undefined) => {
+    let listVals: undefined | string[];
+    if(val === undefined) {
+        return listVals;
+    }
+    const trimmedVal = val.trim();
+    if (trimmedVal.includes(',')) {
+        // try to parse using comma
+        listVals = trimmedVal.split(',').map(x => x.trim()).filter(x => x !== '');
+    } else {
+        // otherwise try spaces
+        listVals = trimmedVal.split(' ')
+            // remove any extraneous spaces
+            .filter(x => x !== ' ' && x !== '');
+    }
+    if (listVals.length === 0) {
+        return undefined;
+    }
+    return listVals;
+}
+
+export const parseOpConfigFromEnv = (): OperatorJsonConfig => {
+    const data = {
+        operator: {
+            name: parseListFromEnv(process.env.OPERATOR),
+            display: process.env.OPERATOR_DISPLAY
+        },
+        credentials: {
+            clientId: process.env.CLIENT_ID,
+            clientSecret: process.env.CLIENT_SECRET,
+            accessToken: process.env.ACCESS_TOKEN,
+            refreshToken: process.env.REFRESH_TOKEN,
+            redirectUri: process.env.REDIRECT_URI,
+        },
+        subreddits: {
+            names: parseListFromEnv(process.env.SUBREDDITS),
+            wikiConfig: process.env.WIKI_CONFIG,
+            heartbeatInterval: process.env.HEARTBEAT !== undefined ? parseInt(process.env.HEARTBEAT) : undefined,
+            dryRun: parseBool(process.env.DRYRUN, undefined),
+        },
+        logging: {
+            // @ts-ignore
+            level: process.env.LOG_LEVEL,
+            path: process.env.LOG_DIR === 'true' ? `${process.cwd()}/logs` : undefined,
+        },
+        snoowrap: {
+            proxy: process.env.PROXY,
+            debug: parseBool(process.env.SNOO_DEBUG, undefined),
+        },
+        web: {
+            enabled: process.env.WEB !== undefined ? parseBool(process.env.WEB) : undefined,
+            port: process.env.PORT !== undefined ? parseInt(process.env.PORT) : undefined,
+            session: {
+                provider: process.env.SESSION_PROVIDER,
+                secret: process.env.SESSION_SECRET
+            }
+        },
+        polling: {
+            sharedMod: parseBool(process.env.SHARE_MOD),
+        },
+        caching: {
+            provider: {
+                store: process.env.CACHING as (CacheProvider | undefined)
+            },
+            authorTTL: process.env.AUTHOR_TTL !== undefined ? parseInt(process.env.AUTHOR_TTL) : undefined
+        },
+        api: {
+            softLimit: process.env.SOFT_LIMIT !== undefined ? parseInt(process.env.SOFT_LIMIT) : undefined,
+            hardLimit: process.env.HARD_LIMIT !== undefined ? parseInt(process.env.HARD_LIMIT) : undefined
+        }
+    }
+
+    return removeUndefinedKeys(data) as OperatorJsonConfig;
+}
+
+// Hierarchy (lower level overwrites above)
+//
+// .env file
+// Actual ENVs (from environment)
+// json config
+// args from cli
+export const parseOperatorConfigFromSources = async (args: any): Promise<OperatorJsonConfig> => {
+    const {logLevel = process.env.LOG_LEVEL, logDir = process.env.LOG_DIR || false} = args || {};
+    const envPath = process.env.OPERATOR_ENV;
+
+    // create a pre config logger to help with debugging
+    const initLogger = getLogger({logLevel, logDir: logDir === true ? `${process.cwd()}/logs` : logDir}, 'init');
+
+    try {
+        const vars = await GetEnvVars({
+            envFile: {
+                filePath: envPath,
+                fallback: true
+            }
+        });
+        // if we found variables in the file of at a fallback path then add them in before we do main arg parsing
+        for (const [k, v] of Object.entries(vars)) {
+            // don't override existing
+            if (process.env[k] === undefined) {
+                process.env[k] = v;
+            }
+        }
+    } catch (err) {
+        let msg = 'No .env file found at default location (./env)';
+        if (envPath !== undefined) {
+            msg = `${msg} or OPERATOR_ENV path (${envPath})`;
+        }
+        initLogger.warn(`${msg} -- this may be normal if neither was provided.`);
+        // mimicking --silent from env-cmd
+        //swallow silently for now 😬
+    }
+
+    const {operatorConfig = process.env.OPERATOR_CONFIG} = args;
+    let configFromFile: OperatorJsonConfig = {};
+    if (operatorConfig !== undefined) {
+        let rawConfig;
+        try {
+            rawConfig = await readJson(operatorConfig, {log: initLogger});
+        } catch (err) {
+            initLogger.error('Cannot continue app startup because operator config file was not parseable.');
+            err.logged = true;
+            throw err;
+        }
+        try {
+            configFromFile = validateJson(rawConfig, operatorSchema, initLogger) as OperatorJsonConfig;
+        } catch (err) {
+            initLogger.error('Cannot continue app startup because operator config file was not valid.');
+            throw err;
+        }
+    }
+    const configFromArgs = parseOpConfigFromArgs(args);
+    const configFromEnv = parseOpConfigFromEnv();
+
+    const mergedConfig = merge.all([configFromEnv, configFromFile, configFromArgs], {
+        arrayMerge: overwriteMerge,
+    });
+
+    return removeUndefinedKeys(mergedConfig) as OperatorJsonConfig;
+}
+
+export const buildOperatorConfigWithDefaults = (data: OperatorJsonConfig): OperatorConfig => {
+    const {
+        operator: {
+            name = [],
+            display = 'Anonymous',
+            botName,
+        } = {},
+        credentials: {
+            clientId: ci,
+            clientSecret: cs,
+            ...restCred
+        } = {},
+        subreddits: {
+            names = [],
+            wikiConfig = 'botconfig/contextbot',
+            heartbeatInterval = 300,
+            dryRun
+        } = {},
+        logging: {
+            level = 'verbose',
+            path,
+        } = {},
+        snoowrap = {},
+        web: {
+            enabled = true,
+            port = 8085,
+            maxLogs = 200,
+            session: {
+                secret = randomId(),
+                provider: sessionProvider = { store: 'memory' },
+            } = {}
+        } = {},
+        polling: {
+            sharedMod = false,
+            limit = 100,
+            interval = 30,
+        } = {},
+        queue: {
+            maxWorkers = 1,
+        } = {},
+        caching,
+        api: {
+            softLimit = 250,
+            hardLimit = 50
+        } = {},
+    } = data;
+
+    let cache: StrongCache;
+
+    if(caching === undefined) {
+        cache = {
+            ...cacheTTLDefaults,
+            provider: {
+                store: 'memory',
+                ...cacheOptDefaults
+            }
+        };
+    } else {
+        const {provider, ...restConfig} = caching;
+        if (typeof provider === 'string') {
+            cache = {
+                ...cacheTTLDefaults,
+                ...restConfig,
+                provider: {
+                    store: provider as CacheProvider,
+                    ...cacheOptDefaults
+                }
+            }
+        } else {
+            const {ttl = 60, max = 500, store = 'memory', ...rest} = provider || {};
+            cache = {
+                ...cacheTTLDefaults,
+                ...restConfig,
+                provider: {
+                    store,
+                    ...cacheOptDefaults,
+                    ...rest,
+                },
+            }
+        }
+    }
+
+    const config: OperatorConfig = {
+        operator: {
+            name: typeof name === 'string' ? [name] : name,
+            display,
+            botName,
+        },
+        credentials: {
+            clientId: (ci as string),
+            clientSecret: (cs as string),
+            ...restCred,
+        },
+        logging: {
+            level,
+            path
+        },
+        snoowrap,
+        subreddits: {
+            names,
+            wikiConfig,
+            heartbeatInterval,
+            dryRun,
+        },
+        web: {
+            enabled,
+            port,
+            session: {
+                secret,
+                provider: typeof sessionProvider === 'string' ? {
+                    ...buildCacheOptionsFromProvider({
+                        ttl: 86400000,
+                        store: sessionProvider,
+                    })
+                } : {
+                    ...buildCacheOptionsFromProvider(sessionProvider),
+                    ttl: 86400000,
+                },
+            },
+            maxLogs,
+        },
+        caching: cache,
+        polling: {
+            sharedMod,
+            limit,
+            interval,
+        },
+        queue: {
+          maxWorkers,
+        },
+        api: {
+            softLimit,
+            hardLimit
+        }
+    };
+
+    return config;
+}

src/JsonConfig.js

@@ -1,3 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=JsonConfig.js.map

src/JsonConfig.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"JsonConfig.js","sourceRoot":"","sources":["JsonConfig.ts"],"names":[],"mappings":""}

src/JsonConfig.ts

@@ -1,4 +1,4 @@
-import {CheckJson} from "./Check";
+import {CheckJson, CommentCheckJson, SubmissionCheckJson} from "./Check";
 import {ManagerOptions} from "./Common/interfaces";
 
 export interface JSONConfig extends ManagerOptions {
@@ -12,5 +12,5 @@ export interface JSONConfig extends ManagerOptions {
      * When a check "passes", and actions are performed, then all subsequent checks are skipped.
      * @minItems 1
      * */
-    checks: CheckJson[]
+    checks: Array<SubmissionCheckJson|CommentCheckJson>
 }

src/Notification/DiscordNotifier.ts

@@ -0,0 +1,48 @@
+import webhook from 'webhook-discord';
+import {NotificationContent} from "../Common/interfaces";
+
+class DiscordNotifier {
+    name: string
+    botName: string
+    type: string = 'Discord';
+    url: string;
+
+    constructor(name: string, botName: string, url: string) {
+        this.name = name;
+        this.url = url;
+        this.botName = botName;
+    }
+
+    async handle(val: NotificationContent) {
+        const h = new webhook.Webhook(this.url);
+
+        const hook = new webhook.MessageBuilder();
+
+        const {logLevel, title, footer, body = ''} = val;
+
+        hook.setName(this.botName === 'ContextMod' ? 'ContextMod' : `(ContextMod) ${this.botName}`)
+            .setTitle(title)
+            .setDescription(body)
+
+        if (footer !== undefined) {
+            // @ts-ignore
+            hook.setFooter(footer, false);
+        }
+
+        switch (logLevel) {
+            case 'error':
+                hook.setColor("##ff0000");
+                break;
+            case 'warn':
+                hook.setColor("#ffe900");
+                break;
+            default:
+                hook.setColor("#00fffa");
+                break;
+        }
+
+        await h.send(hook);
+    }
+}
+
+export default DiscordNotifier;

src/Notification/NotificationManager.ts

@@ -0,0 +1,122 @@
+import {
+    NotificationConfig,
+    NotificationEventConfig,
+    NotificationEvents,
+    NotificationEventType,
+    Notifier
+} from "../Common/interfaces";
+import DiscordNotifier from "./DiscordNotifier";
+import {Logger} from "winston";
+import {mergeArr} from "../util";
+import Subreddit from "snoowrap/dist/objects/Subreddit";
+
+class NotificationManager {
+    notifiers: Notifier[] = [];
+    events: NotificationEvents = [];
+    logger: Logger;
+    subreddit: Subreddit;
+    name: string;
+
+    constructor(logger: Logger, subreddit: Subreddit, displayName: string, botName: string, config?: NotificationConfig) {
+        this.logger = logger.child({leaf: 'Notifications'}, mergeArr);
+        this.subreddit = subreddit;
+        this.name = displayName;
+        if (config !== undefined) {
+            const {events = [], providers = []} = config;
+            this.events = events;
+            for (const p of providers) {
+                switch (p.type) {
+                    case 'discord':
+                        this.notifiers.push(new DiscordNotifier(p.name, botName, p.url));
+                        break;
+                    default:
+                        this.logger.warn(`Notification provider type of ${p.type} not recognized.`);
+                        break;
+                }
+            }
+            if (this.events.length > 0 && this.notifiers.length === 0) {
+                this.logger.warn(`Config specified ${this.events.length} event hooks but not notification providers were setup!`);
+            }
+        }
+    }
+
+    getStats() {
+        let notifiers: string[] = [];
+        if (this.notifiers.length > 0) {
+            notifiers = this.notifiers.map(x => `${x.name} (${x.type})`);
+        }
+        let events: string[] = [];
+        if (this.events.length > 0) {
+            events = this.events.reduce((acc: string[], curr) => {
+                const e = Array.isArray(curr) ? curr : curr.types;
+                for (const ev of e) {
+                    if (!acc.includes(ev)) {
+                        acc.push(ev);
+                    }
+                }
+                return acc;
+            }, []);
+        }
+
+        return {
+            notifiers,
+            events,
+        }
+    }
+
+    async handle(name: NotificationEventType, title: string, body?: string, causedBy?: string, logLevel?: string) {
+
+        if (this.notifiers.length === 0 || this.events.length === 0) {
+            return;
+        }
+
+        let notifiers: Notifier[] = [];
+        for (const e of this.events) {
+            // array of event NotificationEventType
+            if (Array.isArray(e)) {
+                const ev = e as NotificationEventType[];
+                for (const v of ev) {
+                    if (v === name) {
+                        // if we find the event here then we want to sent the event to all configured notifiers
+                        notifiers = notifiers.concat(this.notifiers);
+                    }
+                }
+            } else {
+                // e is a NotificationEventConfig
+                const ev = e as NotificationEventConfig;
+                const hasEvent = ev.types.some(x => x === name);
+                if (hasEvent) {
+                    const p = ev.providers.map(y => y.toLowerCase());
+                    const validNotifiers = this.notifiers.filter(x => p.includes(x.name.toLowerCase()));
+                    notifiers = notifiers.concat(validNotifiers);
+                }
+            }
+        }
+        // remove dups
+        notifiers = notifiers.reduce((acc: Notifier[], curr: Notifier) => {
+            if (!acc.some(x => x.name === curr.name)) {
+                return acc.concat(curr);
+            }
+            return acc;
+        }, []);
+
+        let footer = [];
+        if (causedBy !== undefined) {
+            footer.push(`* Performed by "${causedBy}"`);
+        }
+        footer.push(`* Notification triggered by "${name}"`);
+
+        this.logger.info(`Sending notification for ${name} to providers: ${notifiers.map(x => `${x.name} (${x.type})`).join(', ')}`);
+
+        for (const n of notifiers) {
+            await n.handle({
+                title: `${title} (${this.name})`,
+                body: body || '',
+                footer: footer.length > 0 ? footer.join('\n') : undefined,
+                logLevel
+            });
+        }
+    }
+}
+
+export default NotificationManager;

src/Rule/AttributionRule.ts

@@ -0,0 +1,440 @@
+import {SubmissionRule, SubmissionRuleJSONConfig} from "./SubmissionRule";
+import {ActivityWindowType, DomainInfo, ReferenceSubmission} from "../Common/interfaces";
+import {Rule, RuleOptions, RuleResult} from "./index";
+import Submission from "snoowrap/dist/objects/Submission";
+import {getAttributionIdentifier} from "../Utils/SnoowrapUtils";
+import dayjs from "dayjs";
+import {
+    comparisonTextOp,
+    FAIL,
+    formatNumber,
+    parseGenericValueOrPercentComparison,
+    parseSubredditName,
+    PASS
+} from "../util";
+import { Comment } from "snoowrap/dist/objects";
+import SimpleError from "../Utils/SimpleError";
+
+
+export interface AttributionCriteria {
+    /**
+     * A string containing a comparison operator and a value to compare comments against
+     *
+     * The syntax is `(< OR > OR <= OR >=) <number>[percent sign]`
+     *
+     * * EX `> 12`  => greater than 12 activities originate from same attribution
+     * * EX `<= 10%` => less than 10% of all Activities have the same attribution
+     *
+     * @pattern ^\s*(>|>=|<|<=)\s*(\d+)\s*(%?)(.*)$
+     * @default "> 10%"
+     * */
+    threshold: string
+    window: ActivityWindowType
+    /**
+     * What activities to use for total count when determining what percentage an attribution comprises
+     *
+     * EX:
+     *
+     * Author has 100 activities, 40 are submissions and 60 are comments
+     *
+     * * If `submission` then if 10 submission are for Youtube Channel A then percentage => 10/40 = 25%
+     * * If `all` then if 10 submission are for Youtube Channel A then percentage => 10/100 = 10%
+     *
+     * @default all
+     **/
+    thresholdOn?: 'submissions' | 'all'
+    /**
+     * The minimum number of activities that must exist for this criteria to run
+     * @default 5
+     * */
+    minActivityCount?: number
+
+    /**
+     * A list of domains whose Activities will be tested against `threshold`.
+     *
+     * If this is present then `aggregateOn` is ignored.
+     *
+     * The values are tested as partial strings so you do not need to include full URLs, just the part that matters.
+     *
+     * EX `["youtube"]` will match submissions with the domain `https://youtube.com/c/aChannel`
+     * EX `["youtube.com/c/bChannel"]` will NOT match submissions with the domain `https://youtube.com/c/aChannel`
+     *
+     * If you wish to aggregate on self-posts for a subreddit use the syntax `self.[subreddit]` EX `self.AskReddit`
+     *
+     * **If this Rule is part of a Check for a Submission and you wish to aggregate on the domain of the Submission use the special string `AGG:SELF`**
+     *
+     * If nothing is specified or list is empty (default) aggregate using `aggregateOn`
+     *
+     * @default [[]]
+     * */
+    domains?: string[],
+    /**
+     * Set to `true` if you wish to combine all of the Activities from `domains` to test against `threshold` instead of testing each `domain` individually
+     *
+     * @default false
+     * @examples [false]
+     * */
+    domainsCombined?: boolean,
+
+    /**
+     * Only include Activities from this list of Subreddits (by name, case-insensitive)
+     *
+     *
+     * EX `["mealtimevideos","askscience"]`
+     * @examples ["mealtimevideos","askscience"]
+     * @minItems 1
+     * */
+    include?: string[],
+    /**
+     * Do not include Activities from this list of Subreddits (by name, case-insensitive)
+     *
+     * Will be ignored if `include` is present.
+     *
+     * EX `["mealtimevideos","askscience"]`
+     * @examples ["mealtimevideos","askscience"]
+     * @minItems 1
+     * */
+    exclude?: string[],
+
+    /**
+     * If `domains` is not specified this list determines which categories of domains should be aggregated on. All aggregated domains will be tested against `threshold`
+     *
+     * * If `media` is included then aggregate author's submission history which reddit recognizes as media (youtube, vimeo, etc.)
+     * * If `self` is included then aggregate on author's submission history which are self-post (`self.[subreddit]`) or reddit image/video (i.redd.it / v.redd.it)
+     * * If `link` is included then aggregate author's submission history which is external links but not media
+     *
+     * If nothing is specified or list is empty (default) all domains are aggregated
+     *
+     *  @default undefined
+     *  @examples [[]]
+     * */
+    aggregateOn?: ('media' | 'self' | 'link')[],
+
+    /**
+     * Should the criteria consolidate recognized media domains into the parent domain?
+     *
+     * Submissions to major media domains (youtube, vimeo) can be identified by individual Channel/Author...
+     *
+     * * If `false` then domains will be aggregated at the channel level IE Youtube Channel A (2 counts), Youtube Channel B  (3 counts)
+     * * If `true` then then media domains will be consolidated at domain level and then aggregated IE youtube.com (5 counts)
+     *
+     *  @default false
+     *  @examples [false]
+     * */
+    consolidateMediaDomains?: boolean
+
+    name?: string
+}
+
+const SUBMISSION_DOMAIN = 'AGG:SELF';
+
+const defaultCriteria = [{threshold: '10%', window: 100}];
+
+interface DomainAgg {
+    info: DomainInfo,
+    count: number
+}
+
+export class AttributionRule extends Rule {
+    criteria: AttributionCriteria[];
+    criteriaJoin: 'AND' | 'OR';
+
+    constructor(options: AttributionOptions) {
+        super(options);
+        const {
+            criteria = defaultCriteria,
+            criteriaJoin = 'OR',
+        } = options || {};
+
+        this.criteria = criteria;
+        this.criteriaJoin = criteriaJoin;
+        if (this.criteria.length === 0) {
+            throw new Error('Must provide at least one AttributionCriteria');
+        }
+    }
+
+    getKind(): string {
+        return "Attr";
+    }
+
+    protected getSpecificPremise(): object {
+        return {
+            criteria: this.criteria,
+            criteriaJoin: this.criteriaJoin,
+        }
+    }
+
+    protected async process(item: Comment | Submission): Promise<[boolean, RuleResult]> {
+        let criteriaResults = [];
+
+        for (const criteria of this.criteria) {
+
+            const {
+                threshold = '> 10%',
+                window,
+                thresholdOn = 'all',
+                minActivityCount = 10,
+                aggregateOn = [],
+                consolidateMediaDomains = false,
+                domains = [],
+                domainsCombined = false,
+                include: includeRaw = [],
+                exclude: excludeRaw = [],
+            } = criteria;
+
+            const include = includeRaw.map(x => parseSubredditName(x).toLowerCase());
+            const exclude = excludeRaw.map(x => parseSubredditName(x).toLowerCase());
+
+            const {operator, value, isPercent, extra = ''} = parseGenericValueOrPercentComparison(threshold);
+
+            let activities = thresholdOn === 'submissions' ? await this.resources.getAuthorSubmissions(item.author, {window: window}) : await this.resources.getAuthorActivities(item.author, {window: window});
+            activities = activities.filter(act => {
+                if (include.length > 0) {
+                    return include.some(x => x === act.subreddit.display_name.toLowerCase());
+                } else if (exclude.length > 0) {
+                    return !exclude.some(x => x === act.subreddit.display_name.toLowerCase())
+                }
+                return true;
+            });
+
+            let activityTotal = 0;
+            let firstActivity, lastActivity;
+
+            if(activities.length === 0) {
+                this.logger.debug(`No activities retrieved for criteria`);
+                continue;
+            }
+
+            activityTotal = activities.length;
+            firstActivity = activities[0];
+            lastActivity = activities[activities.length - 1];
+
+            const activityTotalWindow = dayjs.duration(dayjs(firstActivity.created_utc * 1000).diff(dayjs(lastActivity.created_utc * 1000)));
+
+            if (activities.length < minActivityCount) {
+                criteriaResults.push({criteria, activityTotal, activityTotalWindow, triggered: false, aggDomains: [], minCountMet: false});
+                this.logger.debug(`${activities.length } activities retrieved was less than min activities required to run criteria (${minActivityCount})`);
+                continue;
+            }
+
+            const realDomains: DomainInfo[] = domains.map(x => {
+                if(x === SUBMISSION_DOMAIN) {
+                    if(!(item instanceof Submission)) {
+                        throw new SimpleError('Cannot run Attribution Rule with the domain SELF:AGG on a Comment');
+                    }
+                    return getAttributionIdentifier(item, consolidateMediaDomains);
+                }
+                return {display: x, domain: x, aliases: [x]};
+            });
+            const realDomainIdents = realDomains.map(x => x.aliases).flat(1).map(x => x.toLowerCase());
+
+            const submissions: Submission[] = thresholdOn === 'submissions' ? activities as Submission[] : activities.filter(x => x instanceof Submission) as Submission[];
+            const aggregatedSubmissions = submissions.reduce((acc: Map<string, DomainAgg>, sub) => {
+                const domainInfo = getAttributionIdentifier(sub, consolidateMediaDomains)
+
+                let domainType = 'link';
+                if(sub.secure_media !== undefined && sub.secure_media !== null) {
+                    domainType = 'media';
+                } else if((sub.is_self || sub.is_video || sub.domain === 'i.redd.it')) {
+                    domainType = 'self';
+                }
+
+                if(realDomains.length === 0 && aggregateOn.length !== 0) {
+                    if(domainType === 'media' && !aggregateOn.includes('media')) {
+                        return acc;
+                    }
+                    if(domainType === 'self' && !aggregateOn.includes('self')) {
+                        return acc;
+                    }
+                    if(domainType === 'link' && !aggregateOn.includes('link')) {
+                        return acc;
+                    }
+                }
+
+                if(realDomains.length > 0) {
+                    if(domainInfo.aliases.map(x => x.toLowerCase()).some(x => realDomainIdents.includes(x))) {
+                        const domainAgg = acc.get(domainInfo.display) || {info: domainInfo, count: 0};
+                        acc.set(domainInfo.display, {...domainAgg, count: domainAgg.count + 1});
+                    }
+                } else {
+                    const domainAgg = acc.get(domainInfo.display) || {info: domainInfo, count: 0};
+                    acc.set(domainInfo.display, {...domainAgg, count: domainAgg.count + 1});
+                }
+
+                return acc;
+            }, new Map());
+
+            let aggDomains = [];
+
+            if(domainsCombined) {
+                let combinedCount = 0;
+                let domains = [];
+                let triggered = false;
+                for (const [domain, dAgg] of aggregatedSubmissions) {
+                    domains.push(domain);
+                    combinedCount += dAgg.count;
+                }
+                if(isPercent) {
+                    triggered = comparisonTextOp(combinedCount / activityTotal, operator, (value/100));
+                }
+                else {
+                    triggered = comparisonTextOp(combinedCount, operator, value);
+                }
+                const combinedDomain = Array.from(aggregatedSubmissions.values()).map(x => x.info.domain).join(' and ');
+                const combinedDisplay = Array.from(aggregatedSubmissions.values()).map(x => `${x.info.display}${x.info.provider !== undefined ? ` (${x.info.provider})` : ''}`).join(' and ');
+                aggDomains.push({
+                    domain: {display: combinedDisplay, domain: combinedDomain, aliases: [combinedDomain]},
+                    count: combinedCount,
+                    percent: Math.round((combinedCount / activityTotal) * 100),
+                    triggered,
+                });
+
+            } else {
+                for (const [domain, dAgg] of aggregatedSubmissions) {
+                    let triggered = false;
+                    if(isPercent) {
+                        triggered = comparisonTextOp(dAgg.count / activityTotal, operator, (value/100));
+                    }
+                    else {
+                        triggered = comparisonTextOp(dAgg.count, operator, value);
+                    }
+
+                    aggDomains.push({
+                        domain: dAgg.info,
+                        count: dAgg.count,
+                        percent: Math.round((dAgg.count / activityTotal) * 100),
+                        triggered,
+                    });
+                }
+            }
+
+            criteriaResults.push({criteria, activityTotal, activityTotalWindow, aggDomains, minCountMet: true});
+        }
+
+        let criteriaMeta = false;
+        if (this.criteriaJoin === 'OR') {
+            criteriaMeta = criteriaResults.some(x => x.aggDomains.length > 0 && x.aggDomains.some(y => y.triggered === true));
+        } else {
+            criteriaMeta = criteriaResults.every(x => x.aggDomains.length > 0 && x.aggDomains.some(y => y.triggered === true));
+        }
+
+        let usableCriteria = criteriaResults.filter(x => x.aggDomains.length > 0 && x.aggDomains.some(y => y.triggered === true));
+        if (usableCriteria.length === 0) {
+            usableCriteria = criteriaResults.filter(x => x.aggDomains.length > 0)
+        }
+        // probably none hit min count then
+        if(criteriaResults.every(x => x.minCountMet === false)) {
+            const result = `${FAIL} No criteria had their min activity count met`;
+            this.logger.verbose(result);
+            return Promise.resolve([false, this.getResult(false, {result})]);
+        }
+
+        let result;
+        const refCriteriaResults = usableCriteria.find(x => x !== undefined);
+        if(refCriteriaResults === undefined) {
+            result = `${FAIL} No criteria results found??`;
+            return Promise.resolve([false, this.getResult(false, {result})])
+        }
+
+        const {
+            aggDomains = [],
+            activityTotal,
+            activityTotalWindow,
+            criteria: {threshold, window}
+        } = refCriteriaResults;
+
+        const largestCount = aggDomains.reduce((acc, curr) => Math.max(acc, curr.count), 0);
+        const largestPercent = aggDomains.reduce((acc, curr) => Math.max(acc, curr.percent), 0);
+        const smallestCount = aggDomains.reduce((acc, curr) => Math.min(acc, curr.count), aggDomains[0].count);
+        const smallestPercent = aggDomains.reduce((acc, curr) => Math.min(acc, curr.percent), aggDomains[0].percent);
+        const windowText = typeof window === 'number' ? `${activityTotal} Items` : activityTotalWindow.humanize();
+        const countRange = smallestCount === largestCount ? largestCount : `${smallestCount} - ${largestCount}`
+        const percentRange = formatNumber(smallestPercent, {toFixed: 0}) === formatNumber(largestPercent, {toFixed: 0}) ? `${largestPercent}%` : `${smallestPercent}% - ${largestPercent}%`
+
+        let data: any = {};
+        const resultAgnostic = `met the threshold of ${threshold}, with ${countRange} (${percentRange}) of ${activityTotal} Total -- window: ${windowText}`;
+
+        if(criteriaMeta) {
+            result = `${PASS} ${aggDomains.length} Attribution(s) ${resultAgnostic}`;
+            data = {
+                triggeredDomainCount: aggDomains.length,
+                activityTotal,
+                largestCount,
+                largestPercent: `${largestPercent}%`,
+                smallestCount,
+                smallestPercent: `${smallestPercent}%`,
+                countRange,
+                percentRange,
+                domains: aggDomains.map(x => x.domain.domain),
+                domainsDelim: aggDomains.map(x => x.domain.domain).join(', '),
+                titles: aggDomains.map(x => `${x.domain.display}${x.domain.provider !== undefined ? ` (${x.domain.provider})` :''}`),
+                titlesDelim: aggDomains.map(x => `${x.domain.display}${x.domain.provider !== undefined ? ` (${x.domain.provider})` :''}`).join(', '),
+                threshold: threshold,
+                window: windowText
+            };
+        } else {
+            result = `${FAIL} No Attributions ${resultAgnostic}`;
+        }
+
+        this.logger.verbose(result);
+        return Promise.resolve([criteriaMeta, this.getResult(criteriaMeta, {
+            result,
+            data,
+        })]);
+    }
+
+}
+
+interface AttributionConfig extends ReferenceSubmission {
+
+    /**
+     * A list threshold-window values to test attribution against
+     *
+     * If none is provided the default set used is:
+     *
+     * ```
+     * threshold: 10%
+     * window: 100
+     * ```
+     *
+     * @minItems 1
+     * */
+    criteria?: AttributionCriteria[]
+
+    /**
+     * * If `OR` then any set of AttributionCriteria that produce an Attribution over the threshold will trigger the rule.
+     * * If `AND` then all AttributionCriteria sets must product an Attribution over the threshold to trigger the rule.
+     * */
+    criteriaJoin?: 'AND' | 'OR'
+}
+
+export interface AttributionOptions extends AttributionConfig, RuleOptions {
+
+}
+
+/**
+ * Aggregates all of the domain/media accounts attributed to an author's Submission history. If any domain is over the threshold the rule is triggered
+ *
+ * Available data for [Action templating](https://github.com/FoxxMD/context-mod#action-templating):
+ *
+ * ```
+ * triggeredDomainCount => Number of domains that met the threshold
+ * activityTotal        => Number of Activities considered from window
+ * window               => The date range of the Activities considered
+ * largestCount         => The count from the largest aggregated domain
+ * largestPercentage    => The percentage of Activities the largest aggregated domain comprises
+ * smallestCount        => The count from the smallest aggregated domain
+ * smallestPercentage   => The percentage of Activities the smallest aggregated domain comprises
+ * countRange           => A convenience string displaying "smallestCount - largestCount" or just one number if both are the same
+ * percentRange         => A convenience string displaying "smallestPercentage - largestPercentage" or just one percentage if both are the same
+ * domains              => An array of all the domain URLs that met the threshold
+ * domainsDelim         => A comma-delimited string of all the domain URLs that met the threshold
+ * titles               => The friendly-name of the domain if one is present, otherwise the URL (IE youtube.com/c/34ldfa343 => "My Youtube Channel Title")
+ * titlesDelim          => A comma-delimited string of all the domain friendly-names
+ * threshold            => The threshold you configured for this Rule to trigger
+ * url                  => Url of the submission that triggered the rule
+ * ```
+ * */
+export interface AttributionJSONConfig extends AttributionConfig, SubmissionRuleJSONConfig {
+    kind: 'attribution'
+}

src/Rule/AuthorRule.ts

@@ -1,7 +1,7 @@
-import {Author, AuthorOptions, AuthorCriteria, Rule, RuleJSONConfig, RuleOptions, RuleResult} from "./index";
+import {Rule, RuleJSONConfig, RuleOptions, RuleResult} from "./index";
 import {Comment} from "snoowrap";
 import Submission from "snoowrap/dist/objects/Submission";
-import {testAuthorCriteria} from "../Utils/SnoowrapUtils";
+import {Author, AuthorCriteria} from "../Author/Author";
 
 /**
  * Checks the author of the Activity against AuthorCriteria. This differs from a Rule's AuthorOptions as this is a full Rule and will only pass/fail, not skip.
@@ -43,7 +43,7 @@ export class AuthorRule extends Rule {
     }
 
     getKind(): string {
-        return "author";
+        return "Author";
     }
 
     protected getSpecificPremise(): object {
@@ -53,21 +53,21 @@ export class AuthorRule extends Rule {
         };
     }
 
-    protected async process(item: Comment | Submission): Promise<[boolean, RuleResult[]]> {
+    protected async process(item: Comment | Submission): Promise<[boolean, RuleResult]> {
         if (this.include.length > 0) {
             for (const auth of this.include) {
-                if (await this.cache.testAuthorCriteria(item, auth)) {
-                    return Promise.resolve([true, [this.getResult(true)]]);
+                if (await this.resources.testAuthorCriteria(item, auth)) {
+                    return Promise.resolve([true, this.getResult(true)]);
                 }
             }
-            return Promise.resolve([false, [this.getResult(false)]]);
+            return Promise.resolve([false, this.getResult(false)]);
         }
         for (const auth of this.exclude) {
-            if (await this.cache.testAuthorCriteria(item, auth, false)) {
-                return Promise.resolve([true, [this.getResult(true)]]);
+            if (await this.resources.testAuthorCriteria(item, auth, false)) {
+                return Promise.resolve([true, this.getResult(true)]);
             }
         }
-        return Promise.resolve([false, [this.getResult(false)]]);
+        return Promise.resolve([false, this.getResult(false)]);
     }
 }
 

src/Rule/HistoryRule.ts

@@ -1,10 +1,17 @@
 
-import {ActivityWindowType, ThresholdCriteria} from "../Common/interfaces";
+import {ActivityWindowType, CompareValueOrPercent, ThresholdCriteria} from "../Common/interfaces";
 import {Rule, RuleJSONConfig, RuleOptions, RuleResult} from "./index";
 import Submission from "snoowrap/dist/objects/Submission";
 import {getAuthorActivities} from "../Utils/SnoowrapUtils";
 import dayjs from "dayjs";
-import {comparisonTextOp, formatNumber, percentFromString} from "../util";
+import {
+    comparisonTextOp,
+    FAIL,
+    formatNumber,
+    parseGenericValueOrPercentComparison, parseSubredditName,
+    PASS,
+    percentFromString
+} from "../util";
 
 export interface CommentThresholdCriteria extends ThresholdCriteria {
     /**
@@ -20,11 +27,34 @@ export interface CommentThresholdCriteria extends ThresholdCriteria {
  * */
 export interface HistoryCriteria {
 
-    submission?: ThresholdCriteria
-    comment?: CommentThresholdCriteria
     /**
-     * Window defining Activities to consider (both Comment/Submission)
-     */
+     * A string containing a comparison operator and a value to compare submissions against
+     *
+     * The syntax is `(< OR > OR <= OR >=) <number>[percent sign]`
+     *
+     * * EX `> 100`  => greater than 100 submissions
+     * * EX `<= 75%` => submissions are equal to or less than 75% of all Activities
+     *
+     * @pattern ^\s*(>|>=|<|<=)\s*(\d+)\s*(%?)(.*)$
+     * */
+    submission?: CompareValueOrPercent
+    /**
+     * A string containing a comparison operator and a value to compare comments against
+     *
+     * The syntax is `(< OR > OR <= OR >=) <number>[percent sign] [OP]`
+     *
+     * * EX `> 100`  => greater than 100 comments
+     * * EX `<= 75%` => comments are equal to or less than 75% of all Activities
+     *
+     * If your string also contains the text `OP` somewhere **after** `<number>[percent sign]`...:
+     *
+     * * EX `> 100 OP`  => greater than 100 comments as OP
+     * * EX `<= 25% as OP` => Comments as OP were less then or equal to 25% of **all Comments**
+     *
+     * @pattern ^\s*(>|>=|<|<=)\s*(\d+)\s*(%?)(.*)$
+     * */
+    comment?: CompareValueOrPercent
+
     window: ActivityWindowType
 
     /**
@@ -37,7 +67,7 @@ export interface HistoryCriteria {
 
 export class HistoryRule extends Rule {
     criteria: HistoryCriteria[];
-    criteriaJoin: 'AND' | 'OR';
+    condition: 'AND' | 'OR';
     include: string[];
     exclude: string[];
 
@@ -45,18 +75,18 @@ export class HistoryRule extends Rule {
         super(options);
         const {
             criteria,
-            criteriaJoin = 'OR',
+            condition = 'OR',
             include = [],
             exclude = [],
         } = options || {};
 
         this.criteria = criteria;
-        this.criteriaJoin = criteriaJoin;
+        this.condition = condition;
         if (this.criteria.length === 0) {
             throw new Error('Must provide at least one HistoryCriteria');
         }
-        this.include = include.map(x => x.toLowerCase());
-        this.exclude = exclude.map(x => x.toLowerCase());
+        this.include = include.map(x => parseSubredditName(x).toLowerCase());
+        this.exclude = exclude.map(x => parseSubredditName(x).toLowerCase());
     }
 
     getKind(): string {
@@ -71,8 +101,7 @@ export class HistoryRule extends Rule {
         }
     }
 
-    protected async process(item: Submission): Promise<[boolean, RuleResult[]]> {
-        // TODO reuse activities between ActivityCriteria to reduce api calls
+    protected async process(item: Submission): Promise<[boolean, RuleResult]> {
 
         let criteriaResults = [];
 
@@ -80,7 +109,7 @@ export class HistoryRule extends Rule {
 
             const {comment, window, submission, minActivityCount = 5} = criteria;
 
-            let activities = await this.cache.getAuthorActivities(item.author, {window: window});
+            let activities = await this.resources.getAuthorActivities(item.author, {window: window});
             activities = activities.filter(act => {
                 if (this.include.length > 0) {
                     return this.include.some(x => x === act.subreddit.display_name.toLowerCase());
@@ -108,31 +137,32 @@ export class HistoryRule extends Rule {
 
             let commentTrigger = undefined;
             if(comment !== undefined) {
-                const {threshold, condition, asOp = false} = comment;
-                if(typeof threshold === 'string') {
-                    const per = percentFromString(threshold);
+                const {operator, value, isPercent, extra = ''} = parseGenericValueOrPercentComparison(comment);
+                const asOp = extra.toLowerCase().includes('op');
+                if(isPercent) {
+                    const per = value / 100;
                     if(asOp) {
-                        commentTrigger = comparisonTextOp(opTotal / commentTotal, condition, per);
+                        commentTrigger = comparisonTextOp(opTotal / commentTotal, operator, per);
                     } else {
-                        commentTrigger = comparisonTextOp(commentTotal / activityTotal, condition, per);
+                        commentTrigger = comparisonTextOp(commentTotal / activityTotal, operator, per);
                     }
                 } else {
                     if(asOp) {
-                        commentTrigger = comparisonTextOp(opTotal, condition, threshold);
+                        commentTrigger = comparisonTextOp(opTotal, operator, value);
                     } else {
-                        commentTrigger = comparisonTextOp(commentTotal, condition, threshold);
+                        commentTrigger = comparisonTextOp(commentTotal, operator, value);
                     }
                 }
             }
 
             let submissionTrigger = undefined;
             if(submission !== undefined) {
-                const {threshold, condition, } = submission;
-                if(typeof threshold === 'string') {
-                    const per = percentFromString(threshold);
-                    submissionTrigger = comparisonTextOp(submissionTotal / activityTotal, condition, per);
+                const {operator, value, isPercent} = parseGenericValueOrPercentComparison(submission);
+                if(isPercent) {
+                    const per = value / 100;
+                    submissionTrigger = comparisonTextOp(submissionTotal / activityTotal, operator, per);
                 } else {
-                    submissionTrigger = comparisonTextOp(submissionTotal, condition, threshold);
+                    submissionTrigger = comparisonTextOp(submissionTotal, operator, value);
                 }
             }
 
@@ -148,86 +178,104 @@ export class HistoryRule extends Rule {
                 submissionTotal,
                 commentTotal,
                 opTotal,
-                triggered: submissionTrigger === true || commentTrigger === true
+                submissionTrigger,
+                commentTrigger,
+                triggered: (submissionTrigger === undefined || submissionTrigger === true) && (commentTrigger === undefined || commentTrigger === true)
             });
         }
 
-        let criteriaMeta = false;
-        if (this.criteriaJoin === 'OR') {
-            criteriaMeta = criteriaResults.some(x => x.triggered);
+        let criteriaMet = false;
+        let failCriteriaResult: string = '';
+        if (this.condition === 'OR') {
+            criteriaMet = criteriaResults.some(x => x.triggered);
+            if(!criteriaMet) {
+                failCriteriaResult = `${FAIL} No criteria was met`;
+            }
         } else {
-            criteriaMeta = criteriaResults.every(x => x.triggered);
+            criteriaMet = criteriaResults.every(x => x.triggered);
+            if(!criteriaMet) {
+                if(criteriaResults.some(x => x.triggered)) {
+                    const met = criteriaResults.filter(x => x.triggered);
+                    failCriteriaResult = `${FAIL} ${met.length} out of ${criteriaResults.length} criteria met but Rule required all be met. Set log level to debug to see individual results`;
+                    const results = criteriaResults.map(x => this.generateResultDataFromCriteria(x, true));
+                    this.logger.debug(`\r\n ${results.map(x => x.result).join('\r\n')}`);
+                } else {
+                    failCriteriaResult = `${FAIL} No criteria was met`;
+                }
+            }
         }
 
-        if (criteriaMeta) {
+        if(criteriaMet) {
             // use first triggered criteria found
             const refCriteriaResults = criteriaResults.find(x => x.triggered);
-            if (refCriteriaResults !== undefined) {
-                const {
-                    activityTotal,
-                    activityTotalWindow,
-                    submissionTotal,
-                    commentTotal,
-                    opTotal,
-                    criteria: {
-                        comment: {
-                            threshold: cthresh,
-                            condition: ccond,
-                            asOp
-                        } = {},
-                        submission: {
-                            threshold: sthresh,
-                            condition: scond,
-                        } = {},
-                        window,
-                    },
-                    criteria,
-                } = refCriteriaResults;
-
-                const data: any = {
-                    activityTotal,
-                    submissionTotal,
-                    commentTotal,
-                    opTotal,
-                    commentPercent: formatNumber((commentTotal/activityTotal)*100),
-                    submissionPercent: formatNumber((submissionTotal/activityTotal)*100),
-                    opPercent: formatNumber((opTotal/commentTotal)*100),
-                    criteria,
-                    window: typeof window === 'number' ? `${activityTotal} Items` : activityTotalWindow.humanize(true)
-
-                };
-
-                let thresholdSummary = [];
-                let submissionSummary;
-                let commentSummary;
-                if(sthresh !== undefined) {
-                    const suffix = typeof sthresh === 'number' ? 'Items' : `(${formatNumber((submissionTotal/activityTotal)*100)}%) of ${activityTotal} Total`;
-                    submissionSummary = `Submissions (${submissionTotal}) were ${scond}${sthresh} ${suffix}`;
-                    data.submissionSummary = submissionSummary;
-                    thresholdSummary.push(submissionSummary);
-                }
-                if(cthresh !== undefined) {
-                    const totalType = asOp ? 'Comments' : 'Activities'
-                    const countType = asOp ? 'Comments as OP' : 'Comments';
-                    const suffix = typeof cthresh === 'number' ? 'Items' : `(${asOp ? formatNumber((opTotal/commentTotal)*100) : formatNumber((commentTotal/activityTotal)*100)}%) of ${activityTotal} Total ${totalType}`;
-                    commentSummary = `${countType} (${asOp ? opTotal : commentTotal}) were ${ccond}${cthresh} ${suffix}`;
-                    data.commentSummary = commentSummary;
-                    thresholdSummary.push(commentSummary);
-                }
-
-                data.thresholdSummary = thresholdSummary.join(' and ');
-
-                const result = `${thresholdSummary} (${data.window})`;
-                this.logger.verbose(result);
-                return Promise.resolve([true, [this.getResult(true, {
-                    result,
-                    data,
-                })]]);
-            }
+            const resultData = this.generateResultDataFromCriteria(refCriteriaResults);
 
+            this.logger.verbose(`${PASS} ${resultData.result}`);
+            return Promise.resolve([true, this.getResult(true, resultData)]);
         }
 
-        return Promise.resolve([false, [this.getResult(false)]]);
+        return Promise.resolve([false, this.getResult(false, {result: failCriteriaResult})]);
+    }
+
+    protected generateResultDataFromCriteria(results: any, includePassFailSymbols = false) {
+        const {
+            activityTotal,
+            activityTotalWindow,
+            submissionTotal,
+            commentTotal,
+            opTotal,
+            criteria: {
+                comment,
+                submission,
+                window,
+            },
+            criteria,
+            triggered,
+            submissionTrigger,
+            commentTrigger,
+        } = results;
+
+        const data: any = {
+            activityTotal,
+            submissionTotal,
+            commentTotal,
+            opTotal,
+            commentPercent: formatNumber((commentTotal/activityTotal)*100),
+            submissionPercent: formatNumber((submissionTotal/activityTotal)*100),
+            opPercent: formatNumber((opTotal/commentTotal)*100),
+            criteria,
+            window: typeof window === 'number' ? `${activityTotal} Items` : activityTotalWindow.humanize(true),
+            triggered,
+            submissionTrigger,
+            commentTrigger,
+        };
+
+        let thresholdSummary = [];
+        let submissionSummary;
+        let commentSummary;
+        if(submission !== undefined) {
+            const {operator, value, isPercent, displayText} = parseGenericValueOrPercentComparison(submission);
+            const suffix = !isPercent ? 'Items' : `(${formatNumber((submissionTotal/activityTotal)*100)}%) of ${activityTotal} Total`;
+            submissionSummary = `${includePassFailSymbols ? `${submissionTrigger ? PASS : FAIL} ` : ''}Submissions (${submissionTotal}) were${submissionTrigger ? '' : ' not'} ${displayText} ${suffix}`;
+            data.submissionSummary = submissionSummary;
+            thresholdSummary.push(submissionSummary);
+        }
+        if(comment !== undefined) {
+            const {operator, value, isPercent, displayText, extra = ''} = parseGenericValueOrPercentComparison(comment);
+            const asOp = extra.toLowerCase().includes('op');
+            const totalType = asOp ? 'Comments' : 'Activities'
+            const countType = asOp ? 'Comments as OP' : 'Comments';
+            const suffix = !isPercent ? 'Items' : `(${asOp ? formatNumber((opTotal/commentTotal)*100) : formatNumber((commentTotal/activityTotal)*100)}%) of ${activityTotal} Total ${totalType}`;
+            commentSummary = `${includePassFailSymbols ? `${commentTrigger ? PASS : FAIL} ` : ''}${countType} (${asOp ? opTotal : commentTotal}) were${commentTrigger ? '' : ' not'} ${displayText} ${suffix}`;
+            data.commentSummary = commentSummary;
+            thresholdSummary.push(commentSummary);
+        }
+
+        data.thresholdSummary = thresholdSummary.join(' and ');
+
+        const result = `${thresholdSummary} (${data.window})`;
+
+        return {result, data};
     }
 
 }
@@ -247,24 +295,20 @@ interface HistoryConfig  {
      * * If `OR` then any set of Criteria that pass will trigger the Rule
      * * If `AND` then all Criteria sets must pass to trigger the Rule
      * */
-    criteriaJoin?: 'AND' | 'OR'
+    condition?: 'AND' | 'OR'
 
     /**
-     * Only include Submissions from this list of Subreddits.
+     * Only include Submissions from this list of Subreddits (by name, case-insensitive)
      *
-     * A list of subreddits (case-insensitive) to look for. Do not include "r/" prefix.
-     *
-     * EX to match against /r/mealtimevideos and /r/askscience use ["mealtimevideos","askscience"]
+     * EX `["mealtimevideos","askscience"]`
      * @examples ["mealtimevideos","askscience"]
      * @minItems 1
      * */
     include?: string[],
     /**
-     * Do not include Submissions from this list of Subreddits.
+     * Do not include Submissions from this list of Subreddits (by name, case-insensitive)
      *
-     * A list of subreddits (case-insensitive) to look for. Do not include "r/" prefix.
-     *
-     * EX to match against /r/mealtimevideos and /r/askscience use ["mealtimevideos","askscience"]
+     * EX `["mealtimevideos","askscience"]`
      * @examples ["mealtimevideos","askscience"]
      * @minItems 1
      * */
@@ -278,7 +322,7 @@ export interface HistoryOptions extends HistoryConfig, RuleOptions {
 /**
  * Aggregates an Author's submission and comment history. Rule can be triggered on count/percent of total (for either or both comment/sub totals) as well as comment OP total.
  *
- * Available data for [Action templating](https://github.com/FoxxMD/reddit-context-bot#action-templating):
+ * Available data for [Action templating](https://github.com/FoxxMD/context-mod#action-templating):
  *
  * ```
  * activityTotal    => Total number of activities

src/Rule/RecentActivityRule.ts

@@ -1,7 +1,13 @@
 import {Rule, RuleJSONConfig, RuleOptions, RulePremise, RuleResult} from "./index";
 import {Comment, VoteableContent} from "snoowrap";
 import Submission from "snoowrap/dist/objects/Submission";
-import {activityWindowText, parseUsableLinkIdentifier} from "../util";
+import {
+    activityWindowText,
+    comparisonTextOp, FAIL, formatNumber,
+    parseGenericValueOrPercentComparison, parseSubredditName,
+    parseUsableLinkIdentifier,
+    PASS
+} from "../util";
 import {
     ActivityWindow,
     ActivityWindowCriteria,
@@ -32,7 +38,7 @@ export class RecentActivityRule extends Rule {
     }
 
     getKind(): string {
-        return 'Recent Activity';
+        return 'Recent';
     }
 
     getSpecificPremise(): object {
@@ -44,22 +50,21 @@ export class RecentActivityRule extends Rule {
         }
     }
 
-    async process(item: Submission | Comment): Promise<[boolean, RuleResult[]]> {
+    async process(item: Submission | Comment): Promise<[boolean, RuleResult]> {
         let activities;
 
         switch (this.lookAt) {
             case 'comments':
-                activities = await this.cache.getAuthorComments(item.author, {window: this.window});
+                activities = await this.resources.getAuthorComments(item.author, {window: this.window});
                 break;
             case 'submissions':
-                activities = await this.cache.getAuthorSubmissions(item.author, {window: this.window});
+                activities = await this.resources.getAuthorSubmissions(item.author, {window: this.window});
                 break;
             default:
-                activities = await this.cache.getAuthorActivities(item.author, {window: this.window});
+                activities = await this.resources.getAuthorActivities(item.author, {window: this.window});
                 break;
         }
 
-
         let viableActivity = activities;
         if (this.useSubmissionAsReference) {
             if (!(item instanceof Submission)) {
@@ -84,74 +89,83 @@ export class RecentActivityRule extends Rule {
             grouped[s] = (grouped[s] || []).concat(activity);
             return grouped;
         }, {} as Record<string, (Submission | Comment)[]>);
-        let triggeredPerSub = [];
+
+
+        const summaries = [];
         let totalTriggeredOn;
         for (const triggerSet of this.thresholds) {
-            triggeredPerSub = [];
             let currCount = 0;
-            let presentSubs = [];
-            const {count: subCount, totalCount, subreddits = []} = triggerSet;
-            for (const sub of subreddits) {
+            const presentSubs = [];
+            const {threshold = '>= 1', subreddits = []} = triggerSet;
+            for (const sub of subreddits.map(x => parseSubredditName(x))) {
                 const isub = sub.toLowerCase();
                 const {[isub]: tSub = []} = groupedActivity;
-                if(tSub.length > 0) {
+                if (tSub.length > 0) {
                     currCount += tSub.length;
                     presentSubs.push(sub);
-                    if (subCount !== undefined && tSub.length >= subCount) {
-                        triggeredPerSub.push({subreddit: sub, count: tSub.length, threshold: subCount});
-                    }
                 }
             }
-            if(totalCount !== undefined && currCount >= totalCount) {
-                totalTriggeredOn = {subreddits: presentSubs, count: currCount, threshold: totalCount};
+            const {operator, value, isPercent} = parseGenericValueOrPercentComparison(threshold);
+            let sum = {subsWithActivity: presentSubs, subreddits, count: currCount, threshold, triggered: false, testValue: currCount.toString()};
+            if (isPercent) {
+                sum.testValue = `${formatNumber((currCount / viableActivity.length) * 100)}%`;
+                if (comparisonTextOp(currCount / viableActivity.length, operator, value / 100)) {
+                    sum.triggered = true;
+                    totalTriggeredOn = sum;
+                }
+            } else if (comparisonTextOp(currCount, operator, value)) {
+                sum.triggered = true;
+                totalTriggeredOn = sum;
             }
+            summaries.push(sum);
             // if either trigger condition is hit end the iteration early
-            if(triggeredPerSub.length > 0 || totalTriggeredOn !== undefined) {
+            if (totalTriggeredOn !== undefined) {
                 break;
             }
         }
-        if (triggeredPerSub.length > 0 || totalTriggeredOn !== undefined) {
-            let resultArr = [];
-            const data: any = {};
-            if(triggeredPerSub.length > 0) {
-                data.perSubCount = triggeredPerSub.length;
-                data.perSubTotal = triggeredPerSub.reduce((acc, x) => acc + x.count, 0);
-                data.perSubSubredditsSummary = triggeredPerSub.map(x => x.subreddit).join(', ');
-                data.perSubSummary = triggeredPerSub.map(x => `${x.subreddit}(${x.count})`).join(', ');
-                data.perSubThreshold = triggeredPerSub[0].threshold;
-                resultArr.push(`${triggeredPerSub.length} subs have >${triggeredPerSub[0].threshold} activities (${data.perSubTotal} Total)`);
-            }
-            if(totalTriggeredOn !== undefined) {
-                data.totalCount = totalTriggeredOn.count;
-                data.totalSubredditsCount = totalTriggeredOn.subreddits.length;
-                data.totalSubredditsSummary = totalTriggeredOn.subreddits.join(', ')
-                data.totalThreshold = totalTriggeredOn.threshold;
-                data.totalSummary = `${data.totalCount} (>${totalTriggeredOn.threshold}) activities over ${totalTriggeredOn.subreddits.length} subreddits`;
-                resultArr.push(data.totalSummary);
-            }
-            let summary;
-            if(resultArr.length === 2) {
-                // need a shortened summary
-                summary = `${data.perSubCount} per-sub triggers (${data.perSubThreshold}) and ${data.totalCount} total (${data.totalThreshold})`
-            } else {
-                summary = resultArr[0];
-            }
-            const result = resultArr.join(' and ')
+        let result = '';
+        if (totalTriggeredOn !== undefined) {
+            const resultData = this.generateResultData(totalTriggeredOn, viableActivity);
+            result = `${PASS} ${resultData.result}`;
             this.logger.verbose(result);
-            return Promise.resolve([true, [this.getResult(true, {
-                result,
-                data: {
-                    window: typeof this.window === 'number' ? `${activities.length} Items` : activityWindowText(viableActivity),
-                    triggeredOn: triggeredPerSub,
-                    summary,
-                    subSummary: data.totalSubredditsSummary|| data.perSubSubredditsSummary,
-                    subCount: data.totalSubredditsCount || data.perSubCount,
-                    totalCount: data.totalCount || data.perSubTotal
-                }
-            })]]);
+            return Promise.resolve([true, this.getResult(true, resultData)]);
+        } else if(summaries.length === 1) {
+            // can display result if its only one summary otherwise need to log to debug
+            const res = this.generateResultData(summaries[0], viableActivity);
+            result = `${FAIL} ${res.result}`;
+        } else {
+            result = `${FAIL} No criteria was met. Use 'debug' to see individual results`;
+            this.logger.debug(`\r\n ${summaries.map(x => this.generateResultData(x, viableActivity).result).join('\r\n')}`);
         }
 
-        return Promise.resolve([false, [this.getResult(false)]]);
+        this.logger.verbose(result);
+
+        return Promise.resolve([false, this.getResult(false, {result})]);
+    }
+    
+    generateResultData(summary: any, activities: (Submission | Comment)[] = []) {
+        const {
+            count,
+            testValue,
+            subreddits = [],
+            subsWithActivity = [],
+            threshold,
+            triggered
+        } = summary;
+        const relevantSubs = subsWithActivity.length === 0 ? subreddits : subsWithActivity;
+        const totalSummary = `${testValue} activities over ${relevantSubs.length} subreddits ${triggered ? 'met' : 'did not meet'} threshold of ${threshold}`;
+        return {
+            result: totalSummary,
+            data: {
+                window: typeof this.window === 'number' ? `${activities.length} Items` : activityWindowText(activities),
+                summary: totalSummary,
+                subSummary: relevantSubs.join(', '),
+                subCount: relevantSubs.length,
+                totalCount: count,
+                threshold,
+                testValue
+            }
+        };
     }
 }
 
@@ -163,20 +177,26 @@ export class RecentActivityRule extends Rule {
  * */
 export interface SubThreshold extends SubredditCriteria {
     /**
-     * The number of activities in each subreddit from the list that will trigger this rule
-     * @minimum 1
+     * A string containing a comparison operator and a value to compare recent activities against
+     *
+     * The syntax is `(< OR > OR <= OR >=) <number>[percent sign]`
+     *
+     * * EX `> 3`  => greater than 3 activities found in the listed subreddits
+     * * EX `<= 75%` => number of Activities in the subreddits listed are equal to or less than 75% of all Activities
+     *
+     * **Note:** If you use percentage comparison here as well as `useSubmissionAsReference` then "all Activities" is only pertains to Activities that had the Link of the Submission, rather than all Activities from this window.
+     *
+     * @pattern ^\s*(>|>=|<|<=)\s*(\d+)\s*(%?)(.*)$
+     * @default ">= 1"
+     * @examples [">= 1"]
      * */
-    count?: number,
-    /**
-     * The total number of activities across all listed subreddits that will trigger this rule
-     * @minimum 1
-     * */
-    totalCount?: number
+    threshold?: string
 }
 
 interface RecentActivityConfig extends ActivityWindow, ReferenceSubmission {
     /**
      * If present restricts the activities that are considered for count from SubThreshold
+     * @examples ["submissions","comments"]
      * */
     lookAt?: 'comments' | 'submissions',
     /**
@@ -192,7 +212,7 @@ export interface RecentActivityRuleOptions extends RecentActivityConfig, RuleOpt
 /**
  * Checks a user's history for any Activity (Submission/Comment) in the subreddits specified in thresholds
  *
- * Available data for [Action templating](https://github.com/FoxxMD/reddit-context-bot#action-templating):
+ * Available data for [Action templating](https://github.com/FoxxMD/context-mod#action-templating):
  *
  * ```
  * summary    => comma-deliminated list of subreddits that hit the threshold and their count EX subredditA(1), subredditB(4),...
@@ -201,6 +221,9 @@ export interface RecentActivityRuleOptions extends RecentActivityConfig, RuleOpt
  * ```
  * */
 export interface RecentActivityRuleJSONConfig extends RecentActivityConfig, RuleJSONConfig {
+    /**
+     * @examples ["recentActivity"]
+     * */
     kind: 'recentActivity'
 }
 

src/Rule/RegexRule.ts

@@ -0,0 +1,392 @@
+import {Rule, RuleJSONConfig, RuleOptions, RuleResult} from "./index";
+import {Comment} from "snoowrap";
+import Submission from "snoowrap/dist/objects/Submission";
+import {
+    comparisonTextOp, FAIL, isExternalUrlSubmission, parseGenericValueComparison,
+    parseGenericValueOrPercentComparison, parseRegex,
+    PASS
+} from "../util";
+import {
+    ActivityWindowType, JoinOperands,
+} from "../Common/interfaces";
+import dayjs from 'dayjs';
+
+export interface RegexCriteria {
+    /**
+     * A descriptive name that will be used in logging and be available for templating
+     *
+     * @examples ["swear words"]
+     * */
+    name?: string
+    /**
+     * A valid Regular Expression to test content against
+     *
+     * Do not wrap expression in forward slashes
+     *
+     * EX For the expression `/reddit|FoxxMD/` use the value should be `reddit|FoxxMD`
+     *
+     * @examples ["reddit|FoxxMD"]
+     * */
+    regex: string,
+    /**
+     * Regex flags to use
+     * */
+    regexFlags?: string,
+
+    /**
+     * Which content from an Activity to test the regex against
+     *
+     * Only used if the Activity being tested is a Submission -- Comments are only tested against their content (duh)
+     *
+     * @default ["title", "body"]
+     * */
+    testOn?: ('title' | 'body' | 'url')[]
+
+    /**
+     * **When used with `window`** determines what type of Activities to retrieve
+     *
+     * @default "all"
+     * */
+    lookAt?: 'submissions' | 'comments' | 'all',
+
+    /**
+     * A string containing a comparison operator and a value to determine when an Activity is determined "matched"
+     *
+     * The syntax is `(< OR > OR <= OR >=) <number>`
+     *
+     * * EX `> 7  => greater than 7 matches found in the Activity, Activity is matched
+     * * EX `<= 3` => less than 3 matches found in the Activity, Activity is matched
+     *
+     * @pattern ^\s*(>|>=|<|<=)\s*(\d+)(\s+.*)*$
+     * @default "> 0"
+     * @examples ["> 0"]
+     * */
+    matchThreshold?: string,
+
+    /**
+     * An string containing a comparison operator and a value to determine how many Activities need to be "matched" (based on `matchThreshold` condition) to trigger the rule
+     *
+     * **Only useful when used in conjunction with `window`**. If no `window` is specified only the Activity being checked is tested (so the default should/will be used).
+     *
+     * To disable (you are only using `totalMatchThreshold`) set to `null`
+     *
+     * The syntax is `(< OR > OR <= OR >=) <number>[percent sign]`
+     *
+     * * EX `> 3`  => greater than 3 Activities met the `matchThreshold` condition, Rule is triggered
+     * * EX `<= 10%` => less than 10% of all Activities retrieved from `window` met the `matchThreshold` condition, Rule is triggered
+     *
+     * @pattern ^\s*(>|>=|<|<=)\s*(\d+)\s*(%?)(.*)$
+     * @default "> 0"
+     * @examples ["> 0"]
+     * */
+    activityMatchThreshold?: string,
+
+    /**
+     * A string containing a comparison operator and a value to determine how many total matches satisfies the criteria.
+     *
+     * If both this and `activityMatchThreshold` are present then whichever is satisfied first will be used.
+     *
+     * If not using `window` then this should not be used as running `matchThreshold` on one Activity is effectively the same behavior ( but I'm not gonna stop ya ¯\\\_(ツ)\_/¯ )
+     *
+     * The syntax is `(< OR > OR <= OR >=) <number>`
+     *
+     * * EX `> 7`  => greater than 7 matches found in Activity + Author history `window`
+     * * EX `<= 3` => less than 3 matches found in the Activity + Author history `window`
+     *
+     * @pattern ^\s*(>|>=|<|<=)\s*(\d+)(\s+.*)*$
+     * @default "null"
+     * @examples ["> 0"]
+     * */
+    totalMatchThreshold?: string,
+
+    window?: ActivityWindowType
+}
+
+export class RegexRule extends Rule {
+    criteria: RegexCriteria[];
+    condition: JoinOperands;
+
+    constructor(options: RegexRuleOptions) {
+        super(options);
+        const {
+            criteria = [],
+            condition = 'OR'
+        } = options || {};
+        if (criteria.length < 1) {
+            throw new Error('Must provide at least one RegexCriteria');
+        }
+        this.criteria = criteria;
+        this.condition = condition;
+    }
+
+    getKind(): string {
+        return 'Regex';
+    }
+
+    getSpecificPremise(): object {
+        return {
+            criteria: this.criteria,
+            condition: this.condition,
+        }
+    }
+
+    protected async process(item: Submission | Comment): Promise<[boolean, RuleResult]> {
+
+        let criteriaResults = [];
+
+        for (const criteria of this.criteria) {
+
+            const {
+                name,
+                regex,
+                regexFlags,
+                testOn: testOnVals = ['title', 'body'],
+                lookAt = 'all',
+                matchThreshold = '> 0',
+                activityMatchThreshold = '> 0',
+                totalMatchThreshold = null,
+                window,
+            } = criteria;
+
+            // normalize their values and also ensure we don't have duplicates
+            const testOn = testOnVals.map(y => y.toLowerCase()).reduce((acc: string[], curr) => {
+                if (acc.includes(curr)) {
+                    return acc;
+                }
+                return acc.concat(curr);
+            }, []);
+
+            // check regex
+            const reg = new RegExp(regex);
+            // ok cool its a valid regex
+
+            const matchComparison = parseGenericValueComparison(matchThreshold);
+            const activityMatchComparison = activityMatchThreshold === null ? undefined : parseGenericValueOrPercentComparison(activityMatchThreshold);
+            const totalMatchComparison = totalMatchThreshold === null ? undefined : parseGenericValueComparison(totalMatchThreshold);
+
+            // since we are dealing with user input (regex) it's likely they mess up their expression and end up matching *a lot* of stuff
+            // so to keep memory under control only keep the first 100 matches
+            // and just count the rest
+            let matches: string[] = [];
+            let matchCount = 0;
+            let activitiesMatchedCount = 0;
+            let activitiesTested = 0;
+            let activityThresholdMet;
+            let totalThresholdMet;
+
+            // first lets see if the activity we are checking satisfies thresholds
+            // since we may be able to avoid api calls to get history
+            let actMatches = this.getMatchesFromActivity(item, testOn, reg, regexFlags);
+            matches = matches.concat(actMatches).slice(0, 100);
+            matchCount += actMatches.length;
+
+            activitiesTested++;
+            const singleMatched = comparisonTextOp(actMatches.length, matchComparison.operator, matchComparison.value);
+            if (singleMatched) {
+                activitiesMatchedCount++;
+            }
+            if (activityMatchComparison !== undefined) {
+                activityThresholdMet = !activityMatchComparison.isPercent && comparisonTextOp(activitiesMatchedCount, activityMatchComparison.operator, activityMatchComparison.value);
+            }
+            if (totalMatchComparison !== undefined) {
+                totalThresholdMet = comparisonTextOp(matchCount, totalMatchComparison.operator, totalMatchComparison.value);
+            }
+
+            let history: (Submission | Comment)[] = [];
+            if ((activityThresholdMet === false || totalThresholdMet === false) && window !== undefined) {
+                // our checking activity didn't meet threshold requirements and criteria does define window
+                // leh go
+
+                switch (lookAt) {
+                    case 'all':
+                        history = await this.resources.getAuthorActivities(item.author, {window: window});
+                        break;
+                    case 'submissions':
+                        history = await this.resources.getAuthorSubmissions(item.author, {window: window});
+                        break;
+                    case 'comments':
+                        history = await this.resources.getAuthorComments(item.author, {window: window});
+                }
+                // remove current activity it exists in history so we don't count it twice
+                history = history.filter(x => x.id !== item.id);
+                const historyLength = history.length;
+
+                let activityCountFunc: Function | undefined;
+                if (activityMatchComparison !== undefined) {
+                    if (activityMatchComparison.isPercent) {
+                        activityCountFunc = (actsMatched: number) => {
+                            return comparisonTextOp(actsMatched / historyLength, activityMatchComparison.operator, activityMatchComparison.value / 100);
+                        }
+                    } else {
+                        activityCountFunc = (actsMatched: number) => {
+                            return comparisonTextOp(actsMatched, activityMatchComparison.operator, activityMatchComparison.value);
+                        }
+                    }
+                }
+
+                for (const h of history) {
+                    activitiesTested++;
+                    const aMatches = this.getMatchesFromActivity(h, testOn, reg, regexFlags);
+                    matches = matches.concat(aMatches).slice(0, 100);
+                    matchCount += aMatches.length;
+                    const matched = comparisonTextOp(aMatches.length, matchComparison.operator, matchComparison.value);
+                    if (matched) {
+                        activitiesMatchedCount++;
+                    }
+                    if (activityCountFunc !== undefined && activityThresholdMet !== true && activityCountFunc(activitiesMatchedCount)) {
+                        activityThresholdMet = true;
+                    }
+                    if (totalMatchComparison !== undefined && totalThresholdMet !== true) {
+                        totalThresholdMet = comparisonTextOp(matchCount, totalMatchComparison.operator, totalMatchComparison.value)
+                    }
+                }
+            }
+
+            let humanWindow = '';
+            if (history.length > 0) {
+                if (typeof window === 'number') {
+                    humanWindow = `${history.length} Items`;
+                } else {
+                    const firstActivity = history[0];
+                    const lastActivity = history[history.length - 1];
+
+                    humanWindow = dayjs.duration(dayjs(firstActivity.created_utc * 1000).diff(dayjs(lastActivity.created_utc * 1000))).humanize();
+                }
+            } else {
+                humanWindow = '1 Item';
+            }
+
+            const critResults = {
+                criteria: {
+                    name,
+                    regex,
+                    testOn,
+                    matchThreshold,
+                    activityMatchThreshold,
+                    totalMatchThreshold,
+                    window: humanWindow
+                },
+                matches,
+                matchCount,
+                activitiesMatchedCount,
+                activityThresholdMet,
+                totalThresholdMet,
+                triggered: false,
+            };
+
+            if (activityThresholdMet === undefined && totalThresholdMet === undefined) {
+                // user should not have disabled both but in this scenario we'll pretend activityThresholdMet = singleMatch
+                critResults.activityThresholdMet = singleMatched;
+                critResults.triggered = singleMatched;
+            } else {
+                critResults.triggered = activityThresholdMet === true || totalThresholdMet === true;
+            }
+
+            criteriaResults.push(critResults);
+
+            if (this.condition === 'OR') {
+                if (critResults.triggered) {
+                    break;
+                }
+            } else if (!critResults.triggered) {
+                // since its AND and didn't match the whole rule will fail
+                break;
+            }
+        }
+
+        const criteriaMet = this.condition === 'OR' ? criteriaResults.some(x => x.triggered) : criteriaResults.every(x => x.triggered);
+
+        const logSummary: string[] = [];
+        let index = 0;
+        for (const c of criteriaResults) {
+            index++;
+            let msg = `Crit ${c.criteria.name || index} ${c.triggered ? PASS : FAIL}`;
+            if (c.activityThresholdMet !== undefined) {
+                msg = `${msg} -- Activity Match=> ${c.activityThresholdMet ? PASS : FAIL} ${c.activitiesMatchedCount} ${c.criteria.activityMatchThreshold} (Threshold ${c.criteria.matchThreshold})`;
+            }
+            if (c.totalThresholdMet !== undefined) {
+                msg = `${msg} -- Total Matches=> ${c.totalThresholdMet ? PASS : FAIL} ${c.matchCount} ${c.criteria.totalMatchThreshold}`;
+            } else {
+                msg = `${msg} and ${c.matchCount} Total Matches`;
+            }
+            msg = `${msg} (Window: ${c.criteria.window})`;
+            logSummary.push(msg);
+        }
+
+        const result = `${criteriaMet ? PASS : FAIL} ${logSummary.join(' || ')}`;
+        this.logger.verbose(result);
+
+        return Promise.resolve([criteriaMet, this.getResult(criteriaMet, {result, data: criteriaResults})]);
+    }
+
+    protected getMatchesFromActivity(a: (Submission | Comment), testOn: string[], reg: RegExp, flags?: string): string[] {
+        let m: string[] = [];
+        // determine what content we are testing
+        let contents: string[] = [];
+        if (a instanceof Submission) {
+            for (const l of testOn) {
+                switch (l) {
+                    case 'title':
+                        contents.push(a.title);
+                        break;
+                    case 'body':
+                        if (a.is_self) {
+                            contents.push(a.selftext);
+                        }
+                        break;
+                    case 'url':
+                        if (isExternalUrlSubmission(a)) {
+                            contents.push(a.url);
+                        }
+                        break;
+                }
+            }
+        } else {
+            contents.push(a.body)
+        }
+
+        for (const c of contents) {
+            const results = parseRegex(reg, c, flags);
+            if (results.matched) {
+                m = m.concat(results.matches);
+            }
+        }
+        return m;
+    }
+}
+
+interface RegexConfig {
+    /**
+     * A list of Regular Expressions and conditions under which tested Activity(ies) are matched
+     * @minItems 1
+     * @examples [{"regex": "/reddit/", "matchThreshold": "> 3"}]
+     * */
+    criteria: RegexCriteria[]
+    /**
+     * * If `OR` then any set of Criteria that pass will trigger the Rule
+     * * If `AND` then all Criteria sets must pass to trigger the Rule
+     *
+     * @default "OR"
+     * */
+    condition?: 'AND' | 'OR'
+}
+
+export interface RegexRuleOptions extends RegexConfig, RuleOptions {
+}
+
+/**
+ * Test a (list of) Regular Expression against the contents or title of an Activity
+ *
+ * Optionally, specify a `window` of the User's history to additionally test against
+ *
+ * Available data for [Action templating](https://github.com/FoxxMD/context-mod#action-templating):
+ *
+ * */
+export interface RegexRuleJSONConfig extends RegexConfig, RuleJSONConfig {
+    /**
+     * @examples ["regex"]
+     * */
+    kind: 'regex'
+}
+
+export default RegexRule;

src/Rule/RepeatActivityRule.ts

@@ -0,0 +1,367 @@
+import {Rule, RuleJSONConfig, RuleOptions, RuleResult} from "./index";
+import {Comment} from "snoowrap";
+import {
+    activityWindowText,
+    comparisonTextOp, FAIL, isExternalUrlSubmission, isRedditMedia,
+    parseGenericValueComparison, parseSubredditName,
+    parseUsableLinkIdentifier as linkParser, PASS
+} from "../util";
+import {ActivityWindow, ActivityWindowType, ReferenceSubmission} from "../Common/interfaces";
+import Submission from "snoowrap/dist/objects/Submission";
+import dayjs from "dayjs";
+import Fuse from 'fuse.js'
+
+const parseUsableLinkIdentifier = linkParser();
+
+interface RepeatActivityData {
+    identifier: string,
+    sets: (Submission | Comment)[]
+}
+
+interface RepeatActivityReducer {
+    openSets: RepeatActivityData[]
+    allSets: RepeatActivityData[]
+}
+
+const getActivityIdentifier = (activity: (Submission | Comment), length = 200) => {
+    let identifier: string;
+    if (activity instanceof Submission) {
+        if (activity.is_self) {
+            identifier = `${activity.title}${activity.selftext.slice(0, length)}`;
+        } else if(isRedditMedia(activity)) {
+            identifier = activity.title;
+        } else {
+            identifier = parseUsableLinkIdentifier(activity.url) as string;
+        }
+    } else {
+        identifier = activity.body.slice(0, length);
+    }
+    return identifier;
+}
+
+const fuzzyOptions = {
+    includeScore: true,
+    distance: 15
+};
+
+export class RepeatActivityRule extends Rule {
+    threshold: string;
+    window: ActivityWindowType;
+    gapAllowance?: number;
+    useSubmissionAsReference: boolean;
+    lookAt: 'submissions' | 'all';
+    include: string[];
+    exclude: string[];
+    keepRemoved: boolean;
+    minWordCount: number;
+
+    constructor(options: RepeatActivityOptions) {
+        super(options);
+        const {
+            threshold = '> 5',
+            window = 100,
+            gapAllowance,
+            useSubmissionAsReference = true,
+            minWordCount = 1,
+            lookAt = 'all',
+            include = [],
+            exclude = [],
+            keepRemoved = false,
+        } = options;
+        this.minWordCount = minWordCount;
+        this.keepRemoved = keepRemoved;
+        this.threshold = threshold;
+        this.window = window;
+        this.gapAllowance = gapAllowance;
+        this.useSubmissionAsReference = useSubmissionAsReference;
+        this.include = include.map(x => parseSubredditName(x).toLowerCase());
+        this.exclude = exclude.map(x => parseSubredditName(x).toLowerCase());
+        this.lookAt = lookAt;
+    }
+
+    getKind(): string {
+        return 'Repeat';
+    }
+
+    getSpecificPremise(): object {
+        return {
+            threshold: this.threshold,
+            window: this.window,
+            gapAllowance: this.gapAllowance,
+            useSubmissionAsReference: this.useSubmissionAsReference,
+            include: this.include,
+            exclude: this.exclude,
+        }
+    }
+
+    async process(item: Submission|Comment): Promise<[boolean, RuleResult]> {
+        let referenceUrl;
+        if(item instanceof Submission && this.useSubmissionAsReference) {
+            referenceUrl = await item.url;
+        }
+
+        let filterFunc = (x: any) => true;
+        if(this.include.length > 0) {
+            filterFunc = (x: Submission|Comment) => this.include.includes(x.subreddit.display_name.toLowerCase());
+        } else if(this.exclude.length > 0) {
+            filterFunc = (x: Submission|Comment) => !this.exclude.includes(x.subreddit.display_name.toLowerCase());
+        }
+
+        let activities: (Submission | Comment)[] = [];
+        switch (this.lookAt) {
+            case 'submissions':
+                activities = await this.resources.getAuthorSubmissions(item.author, {window: this.window, keepRemoved: this.keepRemoved});
+                break;
+            default:
+                activities = await this.resources.getAuthorActivities(item.author, {window: this.window, keepRemoved: this.keepRemoved});
+                break;
+        }
+
+        const condensedActivities = activities.reduce((acc: RepeatActivityReducer, activity: (Submission | Comment), index: number) => {
+            const {openSets = [], allSets = []} = acc;
+
+            let identifier = getActivityIdentifier(activity);
+            const isUrl = isExternalUrlSubmission(activity);
+            let fu = new Fuse([identifier], !isUrl ? fuzzyOptions : {...fuzzyOptions, distance: 5});
+            const validSub = filterFunc(activity);
+            let minMet = identifier.length >= this.minWordCount;
+
+            let updatedAllSets = [...allSets];
+            let updatedOpenSets: RepeatActivityData[] = [];
+
+            let currIdentifierInOpen = false;
+            const bufferedActivities = this.gapAllowance === undefined || this.gapAllowance === 0 ? [] : activities.slice(Math.max(0, index - this.gapAllowance), Math.max(0, index));
+            for (const o of openSets) {
+                const res = fu.search(o.identifier);
+                const match = res.length > 0;
+                if (match && validSub && minMet) {
+                    updatedOpenSets.push({...o, sets: [...o.sets, activity]});
+                    currIdentifierInOpen = true;
+                } else if (bufferedActivities.some(x => fu.search(getActivityIdentifier(x)).length > 0) && validSub && minMet) {
+                    updatedOpenSets.push(o);
+                } else if(!currIdentifierInOpen && !isUrl) {
+                    updatedAllSets.push(o);
+                }
+            }
+
+            if (!currIdentifierInOpen) {
+                updatedOpenSets.push({identifier, sets: [activity]})
+
+                if(isUrl) {
+                    // could be that a spammer is using different URLs for each submission but similar submission titles so search by title as well
+                    const sub = activity as Submission;
+                    identifier = sub.title;
+                    fu = new Fuse([identifier], !isUrl ? fuzzyOptions : {...fuzzyOptions, distance: 5});
+                    minMet = identifier.length >= this.minWordCount;
+                    for (const o of openSets) {
+                        const res = fu.search(o.identifier);
+                        const match = res.length > 0;
+                        if (match && validSub && minMet) {
+                            updatedOpenSets.push({...o, sets: [...o.sets, activity]});
+                            currIdentifierInOpen = true;
+                        } else if (bufferedActivities.some(x => fu.search(getActivityIdentifier(x)).length > 0) && validSub && minMet && !updatedOpenSets.includes(o)) {
+                            updatedOpenSets.push(o);
+                        } else if(!updatedAllSets.includes(o)) {
+                            updatedAllSets.push(o);
+                        }
+                    }
+
+                    if (!currIdentifierInOpen) {
+                        updatedOpenSets.push({identifier, sets: [activity]})
+                    }
+                }
+            }
+
+            return {openSets: updatedOpenSets, allSets: updatedAllSets};
+
+        }, {openSets: [], allSets: []});
+
+        const allRepeatSets = [...condensedActivities.allSets, ...condensedActivities.openSets];
+
+        const identifierGroupedActivities = allRepeatSets.reduce((acc, repeatActivityData) => {
+            let existingSets = [];
+            if (acc.has(repeatActivityData.identifier)) {
+                existingSets = acc.get(repeatActivityData.identifier);
+            }
+            acc.set(repeatActivityData.identifier, [...existingSets, repeatActivityData.sets].sort((a, b) => b.length < a.length ? 1 : -1));
+            return acc;
+        }, new Map());
+
+        let applicableGroupedActivities = identifierGroupedActivities;
+        if (this.useSubmissionAsReference) {
+            applicableGroupedActivities = new Map();
+            let identifier = getActivityIdentifier(item);
+            let referenceSubmissions = identifierGroupedActivities.get(identifier);
+            if(referenceSubmissions === undefined && isExternalUrlSubmission(item)) {
+                // if external url sub then try by title
+                identifier = (item as Submission).title;
+                referenceSubmissions = identifierGroupedActivities.get(identifier);
+                if(referenceSubmissions === undefined) {
+                    // didn't get by title so go back to url since that's the default
+                    identifier = getActivityIdentifier(item);
+                }
+            }
+
+            applicableGroupedActivities.set(identifier, referenceSubmissions || [])
+        }
+
+        const {operator, value: thresholdValue} = parseGenericValueComparison(this.threshold);
+        const greaterThan = operator.includes('>');
+        let allLessThan = true;
+
+        const identifiersSummary: SummaryData[] = [];
+        for (let [key, value] of applicableGroupedActivities) {
+            const summaryData: SummaryData = {
+                identifier: key,
+                totalSets: value.length,
+                totalTriggeringSets: 0,
+                largestTrigger: 0,
+                sets: [],
+                setsMarkdown: [],
+                triggeringSets: [],
+                triggeringSetsMarkdown: [],
+            };
+            for (let set of value) {
+                const test = comparisonTextOp(set.length, operator, thresholdValue);
+                const md = set.map((x: (Comment | Submission)) => `[${x instanceof Submission ? x.title : getActivityIdentifier(x, 50)}](https://reddit.com${x.permalink}) in ${x.subreddit_name_prefixed} on ${dayjs(x.created_utc * 1000).utc().format()}`);
+
+                summaryData.sets.push(set);
+                summaryData.largestTrigger = Math.max(summaryData.largestTrigger, set.length);
+                summaryData.setsMarkdown.push(md);
+                if (test) {
+                    summaryData.triggeringSets.push(set);
+                    summaryData.totalTriggeringSets++;
+                    summaryData.triggeringSetsMarkdown.push(md);
+                    // }
+                } else if (!greaterThan) {
+                    allLessThan = false;
+                }
+            }
+            identifiersSummary.push(summaryData);
+        }
+
+        const criteriaMet = identifiersSummary.filter(x => x.totalTriggeringSets > 0).length > 0 && (greaterThan || (!greaterThan && allLessThan));
+
+        const largestRepeat = identifiersSummary.reduce((acc, summ) => Math.max(summ.largestTrigger, acc), 0);
+        let result: string;
+        if (criteriaMet || greaterThan) {
+            result = `${criteriaMet ? PASS : FAIL} ${identifiersSummary.filter(x => x.totalTriggeringSets > 0).length} of ${identifiersSummary.length} unique items repeated ${this.threshold} times, largest repeat: ${largestRepeat}`;
+        } else {
+            result = `${FAIL} Not all of ${identifiersSummary.length} unique items repeated ${this.threshold} times, largest repeat: ${largestRepeat}`
+        }
+
+        this.logger.verbose(result);
+
+        if (criteriaMet) {
+            const triggeringSummaries = identifiersSummary.filter(x => x.totalTriggeringSets > 0);
+            return Promise.resolve([true, this.getResult(true, {
+                result,
+                data: {
+                    window: typeof this.window === 'number' ? `${activities.length} Items` : activityWindowText(activities),
+                    totalTriggeringSets: triggeringSummaries.length,
+                    largestRepeat,
+                    threshold: this.threshold,
+                    gapAllowance: this.gapAllowance,
+                    url: referenceUrl,
+                    triggeringSummaries,
+                }
+            })])
+        }
+
+        return Promise.resolve([false, this.getResult(false, {result})]);
+    }
+}
+
+interface SummaryData {
+    identifier: string,
+    totalSets: number,
+    totalTriggeringSets: number,
+    largestTrigger: number,
+    sets: (Comment | Submission)[],
+    setsMarkdown: string[],
+    triggeringSets: (Comment | Submission)[],
+    triggeringSetsMarkdown: string[]
+}
+
+interface RepeatActivityConfig extends ActivityWindow, ReferenceSubmission {
+    /**
+     * The number of repeat submissions that will trigger the rule
+     * @default ">= 5"
+     * */
+    threshold?: string,
+    /**
+     * The number of allowed non-identical Submissions between identical Submissions that can be ignored when checking against the threshold value
+     * */
+    gapAllowance?: number,
+    /**
+     * Only include Submissions from this list of Subreddits (by name, case-insensitive)
+     *
+     * EX `["mealtimevideos","askscience"]`
+     * @examples ["mealtimevideos","askscience"]
+     * @minItems 1
+     * */
+    include?: string[],
+    /**
+     * Do not include Submissions from this list of Subreddits (by name, case-insensitive)
+     *
+     * EX `["mealtimevideos","askscience"]`
+     * @examples ["mealtimevideos","askscience"]
+     * @minItems 1
+     * */
+    exclude?: string[],
+
+    /**
+     * If present determines which activities to consider for gapAllowance.
+     *
+     * * If `submissions` then only the author's submission history is considered IE gapAllowance = 2  ===> can have gap of two submissions between repeats
+     * * If `all` then the author's entire history (submissions/comments) is considered IE gapAllowance = 2  ===> can only have gap of two activities (submissions or comments) between repeats
+     *
+     *  @default all
+     * */
+    lookAt?: 'submissions' | 'all',
+    /**
+     * Count submissions/comments that have previously been removed.
+     *
+     * By default all `Submissions/Commments` that are in a `removed` state will be filtered from `window` (only applies to subreddits you mod).
+     *
+     * Setting to `true` could be useful if you also want to also detected removed repeat posts by a user like for example if automoderator removes multiple, consecutive submissions for not following title format correctly.
+     *
+     * @default false
+     * */
+    keepRemoved?: boolean
+
+    /**
+     * For activities that are text-based this is the minimum number of words required for the activity to be considered for a repeat
+     *
+     * EX if `minimumWordCount=5` and a comment is `what about you` then it is ignored because `3 is less than 5`
+     *
+     * **For self-text submissions** -- title + body text
+     *
+     * **For comments* -- body text
+     *
+     * @default 1
+     * @example [1]
+     * */
+    minWordCount?: number,
+}
+
+export interface RepeatActivityOptions extends RepeatActivityConfig, RuleOptions {
+
+}
+
+/**
+ * Checks a user's history for Submissions with identical content
+ *
+ * Available data for [Action templating](https://github.com/FoxxMD/context-mod#action-templating):
+ *
+ * ```
+ * count      => Total number of repeat Submissions
+ * threshold  => The threshold you configured for this Rule to trigger
+ * url        => Url of the submission that triggered the rule
+ * ```
+ * */
+export interface RepeatActivityJSONConfig extends RepeatActivityConfig, RuleJSONConfig {
+    kind: 'repeatActivity'
+}
+
+export default RepeatActivityRule;

src/Rule/RuleFactory.ts

@@ -1,10 +1,11 @@
 import {RecentActivityRule, RecentActivityRuleJSONConfig} from "./RecentActivityRule";
-import RepeatActivityRule, {RepeatActivityJSONConfig} from "./SubmissionRule/RepeatActivityRule";
+import RepeatActivityRule, {RepeatActivityJSONConfig} from "./RepeatActivityRule";
 import {Rule, RuleJSONConfig} from "./index";
 import AuthorRule, {AuthorRuleJSONConfig} from "./AuthorRule";
-import {AttributionJSONConfig, AttributionRule} from "./SubmissionRule/AttributionRule";
+import {AttributionJSONConfig, AttributionRule} from "./AttributionRule";
 import {Logger} from "winston";
 import HistoryRule, {HistoryJSONConfig} from "./HistoryRule";
+import RegexRule, {RegexRuleJSONConfig} from "./RegexRule";
 
 export function ruleFactory
 (config: RuleJSONConfig, logger: Logger, subredditName: string): Rule {
@@ -25,6 +26,9 @@ export function ruleFactory
         case 'history':
             cfg = config as HistoryJSONConfig;
             return new HistoryRule({...cfg, logger, subredditName});
+        case 'regex':
+            cfg = config as RegexRuleJSONConfig;
+            return new RegexRule({...cfg, logger, subredditName});
         default:
             throw new Error('rule "kind" was not recognized.');
     }

src/Rule/RuleSet.ts

@@ -1,4 +1,4 @@
-import {IRule, Triggerable, Rule, RuleJSONConfig, RuleResult} from "./index";
+import {IRule, Triggerable, Rule, RuleJSONConfig, RuleResult, RuleSetResult} from "./index";
 import {Comment, Submission} from "snoowrap";
 import {ruleFactory} from "./RuleFactory";
 import {createAjvFactory, mergeArr} from "../util";
@@ -8,7 +8,7 @@ import * as RuleSchema from '../Schema/Rule.json';
 import Ajv from 'ajv';
 import {RuleJson, RuleObjectJson} from "../Common/types";
 
-export class RuleSet implements IRuleSet, Triggerable {
+export class RuleSet implements IRuleSet {
     rules: Rule[] = [];
     condition: JoinOperands;
     logger: Logger;
@@ -32,12 +32,12 @@ export class RuleSet implements IRuleSet, Triggerable {
         }
     }
 
-    async run(item: Comment | Submission, existingResults: RuleResult[] = []): Promise<[boolean, RuleResult[]]> {
+    async run(item: Comment | Submission, existingResults: RuleResult[] = []): Promise<[boolean, RuleSetResult]> {
         let results: RuleResult[] = [];
         let runOne = false;
         for (const r of this.rules) {
             const combinedResults = [...existingResults, ...results];
-            const [passed, [result]] = await r.run(item, combinedResults);
+            const [passed, result] = await r.run(item, combinedResults);
             //results = results.concat(determineNewResults(combinedResults, result));
             results.push(result);
             // skip rule if author check failed
@@ -47,17 +47,30 @@ export class RuleSet implements IRuleSet, Triggerable {
             runOne = true;
             if (passed) {
                 if (this.condition === 'OR') {
-                    return [true, results];
+                    return [true, this.generateResultSet(true, results)];
                 }
             } else if (this.condition === 'AND') {
-                return [false, results];
+                return [false, this.generateResultSet(false, results)];
             }
         }
         // if no rules were run it's the same as if nothing was triggered
         if (!runOne) {
-            return [false, results];
+            return [false, this.generateResultSet(false, results)];
         }
-        return [true, results];
+        if(this.condition === 'OR') {
+            // if OR and did not return already then none passed
+            return [false, this.generateResultSet(false, results)];
+        }
+        // otherwise AND and did not return already so all passed
+        return [true, this.generateResultSet(true, results)];
+    }
+
+    generateResultSet(triggered: boolean, results: RuleResult[]): RuleSetResult {
+        return {
+            results,
+            triggered,
+            condition: this.condition
+        };
     }
 }
 

src/Rule/SubmissionRule/AttributionRule.ts

@@ -1,344 +0,0 @@
-import {SubmissionRule, SubmissionRuleJSONConfig} from "./index";
-import {ActivityWindowType, ReferenceSubmission} from "../../Common/interfaces";
-import {RuleOptions, RuleResult} from "../index";
-import Submission from "snoowrap/dist/objects/Submission";
-import {getAttributionIdentifier} from "../../Utils/SnoowrapUtils";
-import dayjs from "dayjs";
-
-
-export interface AttributionCriteria {
-    /**
-     * The number or percentage to trigger this rule at
-     *
-     * * If `threshold` is a `number` then it is the absolute number of attribution instances to trigger at
-     * * If `threshold` is a `string` with percentage (EX `40%`) then it is the percentage of the total (see `lookAt`) this attribution must reach to trigger
-     *
-     * @default 10%
-     * */
-    threshold: number | string
-    window: ActivityWindowType
-    /**
-     * What activities to use for total count when determining what percentage an attribution comprises
-     *
-     * EX:
-     *
-     * Author has 100 activities, 40 are submissions and 60 are comments
-     *
-     * * If `submission` then if 10 submission are for Youtube Channel A then percentage => 10/40 = 25%
-     * * If `all` then if 10 submission are for Youtube Channel A then percentage => 10/100 = 10%
-     *
-     * @default all
-     **/
-    thresholdOn?: 'submissions' | 'all'
-    /**
-     * The minimum number of activities that must exist for this criteria to run
-     * @default 5
-     * */
-    minActivityCount?: number
-    name?: string
-}
-
-const defaultCriteria = [{threshold: '10%', window: 100}];
-
-export class AttributionRule extends SubmissionRule {
-    criteria: AttributionCriteria[];
-    criteriaJoin: 'AND' | 'OR';
-    useSubmissionAsReference: boolean;
-    lookAt: 'media' | 'all' = 'media';
-    include: string[];
-    exclude: string[];
-    aggregateMediaDomains: boolean = false;
-    includeSelf: boolean = false;
-
-    constructor(options: AttributionOptions) {
-        super(options);
-        const {
-            criteria = defaultCriteria,
-            criteriaJoin = 'OR',
-            include = [],
-            exclude = [],
-            lookAt = 'media',
-            aggregateMediaDomains = false,
-            useSubmissionAsReference = true,
-            includeSelf = false,
-        } = options || {};
-
-        this.criteria = criteria;
-        this.criteriaJoin = criteriaJoin;
-        if (this.criteria.length === 0) {
-            throw new Error('Must provide at least one AttributionCriteria');
-        }
-        this.include = include.map(x => x.toLowerCase());
-        this.exclude = exclude.map(x => x.toLowerCase());
-        this.lookAt = lookAt;
-        this.aggregateMediaDomains = aggregateMediaDomains;
-        this.includeSelf = includeSelf;
-        this.useSubmissionAsReference = useSubmissionAsReference;
-    }
-
-    getKind(): string {
-        return "Attribution";
-    }
-
-    protected getSpecificPremise(): object {
-        return {
-            criteria: this.criteria,
-            useSubmissionAsReference: this.useSubmissionAsReference,
-            include: this.include,
-            exclude: this.exclude,
-            lookAt: this.lookAt,
-            aggregateMediaDomains: this.aggregateMediaDomains,
-            includeSelf: this.includeSelf,
-        }
-    }
-
-    protected async process(item: Submission): Promise<[boolean, RuleResult[]]> {
-        const referenceUrl = await item.url;
-        if (referenceUrl === undefined && this.useSubmissionAsReference) {
-            throw new Error(`Cannot run Rule ${this.name} because submission is not a link`);
-        }
-
-        const refDomain = this.aggregateMediaDomains ? item.domain : item.secure_media?.oembed?.author_url;
-        const refDomainTitle = this.aggregateMediaDomains ? (item.secure_media?.oembed?.provider_name || item.domain) : item.secure_media?.oembed?.author_name;
-
-        // TODO reuse activities between ActivityCriteria to reduce api calls
-
-        let criteriaResults = [];
-
-        for (const criteria of this.criteria) {
-
-            const {threshold, window, thresholdOn = 'all', minActivityCount = 5} = criteria;
-
-            let percentVal;
-            if (typeof threshold === 'string') {
-                percentVal = Number.parseInt(threshold.replace('%', '')) / 100;
-            }
-
-            let activities = thresholdOn === 'submissions' ? await this.cache.getAuthorSubmissions(item.author, {window: window}) : await this.cache.getAuthorActivities(item.author, {window: window});
-            activities = activities.filter(act => {
-                if (this.include.length > 0) {
-                    return this.include.some(x => x === act.subreddit.display_name.toLowerCase());
-                } else if (this.exclude.length > 0) {
-                    return !this.exclude.some(x => x === act.subreddit.display_name.toLowerCase())
-                }
-                return true;
-            });
-
-            if (activities.length < minActivityCount) {
-                continue;
-            }
-            //const activities = await getAuthorSubmissions(item.author, {window: window}) as Submission[];
-
-            const submissions: Submission[] = thresholdOn === 'submissions' ? activities as Submission[] : activities.filter(x => x instanceof Submission) as Submission[];
-            const aggregatedSubmissions = submissions.reduce((acc: Map<string, number>, sub) => {
-                if (this.lookAt === 'media' && sub.secure_media === undefined) {
-                    return acc;
-                }
-
-                const domain = getAttributionIdentifier(sub, this.aggregateMediaDomains)
-
-                if ((sub.is_self || sub.is_video || domain === 'i.redd.it') && !this.includeSelf) {
-                    return acc;
-                }
-
-                const count = acc.get(domain) || 0;
-
-                acc.set(domain, count + 1);
-
-                return acc;
-            }, new Map());
-
-            let activityTotal = 0;
-            let firstActivity, lastActivity;
-
-            activityTotal = activities.length;
-            firstActivity = activities[0];
-            lastActivity = activities[activities.length - 1];
-
-            // if (this.includeInTotal === 'submissions') {
-            //     activityTotal = activities.length;
-            //     firstActivity = activities[0];
-            //     lastActivity = activities[activities.length - 1];
-            // } else {
-            //     const dur = typeof window === 'number' ? dayjs.duration(dayjs().diff(dayjs(activities[activities.length - 1].created * 1000))) : window;
-            //     const allActivities = await getAuthorActivities(item.author, {window: dur});
-            //     activityTotal = allActivities.length;
-            //     firstActivity = allActivities[0];
-            //     lastActivity = allActivities[allActivities.length - 1];
-            // }
-
-            const activityTotalWindow = dayjs.duration(dayjs(firstActivity.created_utc * 1000).diff(dayjs(lastActivity.created_utc * 1000)));
-
-            let triggeredDomains = [];
-            for (const [domain, subCount] of aggregatedSubmissions) {
-                let triggered = false;
-                if (percentVal !== undefined) {
-
-                    triggered = percentVal <= subCount / activityTotal;
-                } else if (subCount >= threshold) {
-                    triggered = true;
-                }
-
-                if (triggered) {
-                    // look for author channel
-                    const withChannel = submissions.find(x => x.secure_media?.oembed?.author_url === domain || x.secure_media?.oembed?.author_name === domain);
-                    triggeredDomains.push({
-                        domain,
-                        title: withChannel !== undefined ? (withChannel.secure_media?.oembed?.author_name || withChannel.secure_media?.oembed?.author_url) : domain,
-                        count: subCount,
-                        percent: Math.round((subCount / activityTotal) * 100)
-                    });
-                }
-            }
-
-            if (this.useSubmissionAsReference) {
-                // filter triggeredDomains to only reference
-                triggeredDomains = triggeredDomains.filter(x => x.domain === refDomain || x.domain === refDomainTitle);
-            }
-
-            criteriaResults.push({criteria, activityTotal, activityTotalWindow, triggeredDomains});
-        }
-
-        let criteriaMeta = false;
-        if (this.criteriaJoin === 'OR') {
-            criteriaMeta = criteriaResults.some(x => x.triggeredDomains.length > 0);
-        } else {
-            criteriaMeta = criteriaResults.every(x => x.triggeredDomains.length > 0);
-        }
-
-        if (criteriaMeta) {
-            // use first triggered criteria found
-            const refCriteriaResults = criteriaResults.find(x => x.triggeredDomains.length > 0);
-            if (refCriteriaResults !== undefined) {
-                const {
-                    triggeredDomains,
-                    activityTotal,
-                    activityTotalWindow,
-                    criteria: {threshold, window}
-                } = refCriteriaResults;
-
-                const largestCount = triggeredDomains.reduce((acc, curr) => Math.max(acc, curr.count), 0);
-                const largestPercent = triggeredDomains.reduce((acc, curr) => Math.max(acc, curr.percent), 0);
-
-                const data: any = {
-                    triggeredDomainCount: triggeredDomains.length,
-                    activityTotal,
-                    largestCount,
-                    largestPercent,
-                    threshold: threshold,
-                    window: typeof window === 'number' ? `${activityTotal} Items` : activityTotalWindow.humanize()
-
-                };
-                if (this.useSubmissionAsReference) {
-                    data.refDomain = refDomain;
-                    data.refDomainTitle = refDomainTitle;
-                }
-
-                const result = `${triggeredDomains.length} Attribution(s) met the threshold of ${threshold}, largest being ${largestCount} (${largestPercent}%) of ${activityTotal} Total -- window: ${data.window}`;
-                this.logger.verbose(result);
-                return Promise.resolve([true, [this.getResult(true, {
-                    result,
-                    data,
-                })]]);
-            }
-
-        }
-
-        return Promise.resolve([false, [this.getResult(false)]]);
-    }
-
-}
-
-interface AttributionConfig extends ReferenceSubmission {
-
-    /**
-     * A list threshold-window values to test attribution against
-     *
-     * If none is provided the default set used is:
-     *
-     * ```
-     * threshold: 10%
-     * window: 100
-     * ```
-     *
-     * @minItems 1
-     * */
-    criteria?: AttributionCriteria[]
-
-    /**
-     * * If `OR` then any set of AttributionCriteria that produce an Attribution over the threshold will trigger the rule.
-     * * If `AND` then all AttributionCriteria sets must product an Attribution over the threshold to trigger the rule.
-     * */
-    criteriaJoin?: 'AND' | 'OR'
-
-    /**
-     * Only include Submissions from this list of Subreddits.
-     *
-     * A list of subreddits (case-insensitive) to look for. Do not include "r/" prefix.
-     *
-     * EX to match against /r/mealtimevideos and /r/askscience use ["mealtimevideos","askscience"]
-     * @examples ["mealtimevideos","askscience"]
-     * @minItems 1
-     * */
-    include?: string[],
-    /**
-     * Do not include Submissions from this list of Subreddits.
-     *
-     * A list of subreddits (case-insensitive) to look for. Do not include "r/" prefix.
-     *
-     * EX to match against /r/mealtimevideos and /r/askscience use ["mealtimevideos","askscience"]
-     * @examples ["mealtimevideos","askscience"]
-     * @minItems 1
-     * */
-    exclude?: string[],
-
-    /**
-     * Determines which type of attribution to look at
-     *
-     * * If `media` then only the author's submission history which reddit recognizes as media (youtube, vimeo, etc.) will be considered
-     * * If `all` then all domains (EX youtube.com, twitter.com) from the author's submission history will be considered
-     *
-     *  @default all
-     * */
-    lookAt?: 'media' | 'all',
-
-    /**
-     * Should the rule aggregate recognized media domains into the parent domain?
-     *
-     * Submissions to major media domains (youtube, vimeo) can be identified by individual Channel/Author...
-     *
-     * * If `false` then aggregate will occur at the channel level IE Youtube Channel A (2 counts), Youtube Channel B  (3 counts)
-     * * If `true` then then aggregation will occur at the domain level IE youtube.com (5 counts)
-     *
-     *  @default false
-     * */
-    aggregateMediaDomains?: boolean
-
-    /**
-     * Include reddit `self.*` domains in aggregation?
-     *
-     * Self-posts are aggregated under the domain `self.[subreddit]`. If you wish to include these domains in aggregation set this to `true`
-     *
-     *  @default false
-     * */
-    includeSelf?: boolean
-}
-
-export interface AttributionOptions extends AttributionConfig, RuleOptions {
-
-}
-
-/**
- * Aggregates all of the domain/media accounts attributed to an author's Submission history. If any domain is over the threshold the rule is triggered
- *
- * Available data for [Action templating](https://github.com/FoxxMD/reddit-context-bot#action-templating):
- *
- * ```
- * count      => Total number of repeat Submissions
- * threshold  => The threshold you configured for this Rule to trigger
- * url        => Url of the submission that triggered the rule
- * ```
- * */
-export interface AttributionJSONConfig extends AttributionConfig, SubmissionRuleJSONConfig {
-    kind: 'attribution'
-}

src/Rule/SubmissionRule/RepeatActivityRule.ts

@@ -1,258 +0,0 @@
-import {SubmissionRule, SubmissionRuleJSONConfig} from "./index";
-import {RuleOptions, RuleResult} from "../index";
-import {Comment} from "snoowrap";
-import {activityWindowText, parseUsableLinkIdentifier as linkParser} from "../../util";
-import {ActivityWindow, ActivityWindowType, ReferenceSubmission} from "../../Common/interfaces";
-import Submission from "snoowrap/dist/objects/Submission";
-import dayjs from "dayjs";
-
-const parseUsableLinkIdentifier = linkParser();
-
-interface RepeatActivityData {
-    identifier: string,
-    sets: (Submission | Comment)[]
-}
-
-interface RepeatActivityReducer {
-    openSets: RepeatActivityData[]
-    allSets: RepeatActivityData[]
-}
-
-const getActivityIdentifier = (activity: (Submission | Comment), length = 200) => {
-    let identifier: string;
-    if (activity instanceof Submission) {
-        if (activity.is_self) {
-            identifier = activity.selftext.slice(0, length);
-        } else {
-            identifier = parseUsableLinkIdentifier(activity.url) as string;
-        }
-    } else {
-        identifier = activity.body.slice(0, length);
-    }
-    return identifier;
-}
-
-export class RepeatActivityRule extends SubmissionRule {
-    threshold: number;
-    window: ActivityWindowType;
-    gapAllowance?: number;
-    useSubmissionAsReference: boolean;
-    lookAt: 'submissions' | 'all';
-    include: string[];
-    exclude: string[];
-
-    constructor(options: RepeatActivityOptions) {
-        super(options);
-        const {
-            threshold = 5,
-            window = 15,
-            gapAllowance,
-            useSubmissionAsReference = true,
-            lookAt = 'all',
-            include = [],
-            exclude = []
-        } = options;
-        this.threshold = threshold;
-        this.window = window;
-        this.gapAllowance = gapAllowance;
-        this.useSubmissionAsReference = useSubmissionAsReference;
-        this.include = include;
-        this.exclude = exclude;
-        this.lookAt = lookAt;
-    }
-
-    getKind(): string {
-        return 'Repeat Activity';
-    }
-
-    getSpecificPremise(): object {
-        return {
-            threshold: this.threshold,
-            window: this.window,
-            gapAllowance: this.gapAllowance,
-            useSubmissionAsReference: this.useSubmissionAsReference,
-            include: this.include,
-            exclude: this.exclude,
-        }
-    }
-
-    async process(item: Submission): Promise<[boolean, RuleResult[]]> {
-        const referenceUrl = await item.url;
-        if (referenceUrl === undefined && this.useSubmissionAsReference) {
-            throw new Error(`Cannot run Rule ${this.name} because submission is not a link`);
-        }
-
-        let activities: (Submission | Comment)[] = [];
-        switch (this.lookAt) {
-            case 'submissions':
-                activities = await this.cache.getAuthorSubmissions(item.author, {window: this.window});
-                break;
-            default:
-                activities = await this.cache.getAuthorActivities(item.author, {window: this.window});
-                break;
-        }
-
-        const condensedActivities = activities.reduce((acc: RepeatActivityReducer, activity: (Submission | Comment), index: number) => {
-            const {openSets = [], allSets = []} = acc;
-
-            let identifier = getActivityIdentifier(activity);
-
-            let updatedAllSets = [...allSets];
-            let updatedOpenSets = [];
-            let currIdentifierInOpen = false;
-            const bufferedActivities = this.gapAllowance === undefined || this.gapAllowance === 0 ? [] : activities.slice(Math.max(0, index - this.gapAllowance), Math.max(0, index));
-            for (const o of openSets) {
-                if (o.identifier === identifier) {
-                    updatedOpenSets.push({...o, sets: [...o.sets, activity]});
-                    currIdentifierInOpen = true;
-                } else if (bufferedActivities.some(x => getActivityIdentifier(x) === identifier)) {
-                    updatedOpenSets.push(o);
-                } else {
-                    updatedAllSets.push(o);
-                }
-            }
-
-            if (!currIdentifierInOpen) {
-                updatedOpenSets.push({identifier, sets: [activity]})
-            }
-
-            return {openSets: updatedOpenSets, allSets: updatedAllSets};
-
-        }, {openSets: [], allSets: []});
-
-        const allRepeatSets = [...condensedActivities.allSets, ...condensedActivities.openSets];
-
-        const identifierGroupedActivities = allRepeatSets.reduce((acc, repeatActivityData) => {
-            let existingSets = [];
-            if (acc.has(repeatActivityData.identifier)) {
-                existingSets = acc.get(repeatActivityData.identifier);
-            }
-            acc.set(repeatActivityData.identifier, [...existingSets, repeatActivityData.sets].sort((a, b) => b.length < a.length ? 1 : -1));
-            return acc;
-        }, new Map());
-
-        let applicableGroupedActivities = identifierGroupedActivities;
-        if (this.useSubmissionAsReference) {
-            applicableGroupedActivities = new Map();
-            const referenceSubmissions = identifierGroupedActivities.get(getActivityIdentifier(item));
-            applicableGroupedActivities.set(getActivityIdentifier(item), referenceSubmissions || [])
-        }
-
-        const identifiersSummary: SummaryData[] = [];
-        for (let [key, value] of applicableGroupedActivities) {
-            const summaryData = {
-                identifier: key,
-                totalSets: value.length,
-                totalTriggeringSets: 0,
-                largestTrigger: 0,
-                triggeringSets: [],
-                triggeringSetsMarkdown: [],
-            };
-            for (let set of value) {
-                if (set.length >= this.threshold) {
-                    // @ts-ignore
-                    summaryData.triggeringSets.push(set);
-                    summaryData.totalTriggeringSets++;
-                    summaryData.largestTrigger = Math.max(summaryData.largestTrigger, set.length);
-                    const md = set.map((x: (Comment | Submission)) => `[${x instanceof Submission ? x.title : getActivityIdentifier(x, 50)}](https://reddit.com${x.permalink}) in ${x.subreddit_name_prefixed} on ${dayjs(x.created_utc * 1000).utc().format()}`);
-                    // @ts-ignore
-                    summaryData.triggeringSetsMarkdown.push(md);
-                }
-            }
-            identifiersSummary.push(summaryData);
-        }
-
-        const triggeringSummaries = identifiersSummary.filter(x => x.totalTriggeringSets > 0)
-        if (triggeringSummaries.length > 0) {
-            const largestRepeat = triggeringSummaries.reduce((acc, summ) => Math.max(summ.largestTrigger, acc), 0);
-            const result = `${triggeringSummaries.length} of ${identifiersSummary.length} unique items repeated >=${this.threshold} (threshold) times, largest repeat: ${largestRepeat}`;
-            this.logger.verbose(result);
-            return Promise.resolve([true, [this.getResult(true, {
-                result,
-                data: {
-                    window: typeof this.window === 'number' ? `${activities.length} Items` : activityWindowText(activities),
-                    totalTriggeringSets: triggeringSummaries.length,
-                    largestRepeat,
-                    threshold: this.threshold,
-                    gapAllowance: this.gapAllowance,
-                    url: referenceUrl,
-                    triggeringSummaries,
-                }
-            })]]);
-        }
-
-        return Promise.resolve([false, [this.getResult(false)]]);
-    }
-}
-
-interface SummaryData {
-    identifier: string,
-    totalSets: number,
-    totalTriggeringSets: number,
-    largestTrigger: number,
-    triggeringSets: (Comment | Submission)[],
-    triggeringSetsMarkdown: string[]
-}
-
-interface RepeatActivityConfig extends ActivityWindow, ReferenceSubmission {
-    /**
-     * The number of repeat submissions that will trigger the rule
-     * @default 5
-     * */
-    threshold?: number,
-    /**
-     * The number of allowed non-identical Submissions between identical Submissions that can be ignored when checking against the threshold value
-     * */
-    gapAllowance?: number,
-    /**
-     * Only include Submissions from this list of Subreddits.
-     *
-     * A list of subreddits (case-insensitive) to look for. Do not include "r/" prefix.
-     *
-     * EX to match against /r/mealtimevideos and /r/askscience use ["mealtimevideos","askscience"]
-     * @examples ["mealtimevideos","askscience"]
-     * @minItems 1
-     * */
-    include?: string[],
-    /**
-     * Do not include Submissions from this list of Subreddits.
-     *
-     * A list of subreddits (case-insensitive) to look for. Do not include "r/" prefix.
-     *
-     * EX to match against /r/mealtimevideos and /r/askscience use ["mealtimevideos","askscience"]
-     * @examples ["mealtimevideos","askscience"]
-     * @minItems 1
-     * */
-    exclude?: string[],
-
-    /**
-     * If present determines which activities to consider for gapAllowance.
-     *
-     * * If `submissions` then only the author's submission history is considered IE gapAllowance = 2  ===> can have gap of two submissions between repeats
-     * * If `all` then the author's entire history (submissions/comments) is considered IE gapAllowance = 2  ===> can only have gap of two activities (submissions or comments) between repeats
-     *
-     *  @default all
-     * */
-    lookAt?: 'submissions' | 'all',
-}
-
-export interface RepeatActivityOptions extends RepeatActivityConfig, RuleOptions {
-
-}
-
-/**
- * Checks a user's history for Submissions with identical content
- *
- * Available data for [Action templating](https://github.com/FoxxMD/reddit-context-bot#action-templating):
- *
- * ```
- * count      => Total number of repeat Submissions
- * threshold  => The threshold you configured for this Rule to trigger
- * url        => Url of the submission that triggered the rule
- * ```
- * */
-export interface RepeatActivityJSONConfig extends RepeatActivityConfig, SubmissionRuleJSONConfig {
-    kind: 'repeatActivity'
-}
-
-export default RepeatActivityRule;

src/Rule/SubmissionRule/index.js

@@ -1,8 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SubmissionRule = void 0;
-const index_1 = require("../index");
-class SubmissionRule extends index_1.Rule {
-}
-exports.SubmissionRule = SubmissionRule;
-//# sourceMappingURL=index.js.map

src/Rule/SubmissionRule/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;;AAAA,oCAAqD;AAErD,MAAsB,cAAe,SAAQ,YAAI;CAEhD;AAFD,wCAEC"}

src/Rule/index.ts

@@ -2,12 +2,14 @@ import {Comment} from "snoowrap";
 import Submission from "snoowrap/dist/objects/Submission";
 import {Logger} from "winston";
 import {findResultByPremise, mergeArr} from "../util";
-import {testAuthorCriteria} from "../Utils/SnoowrapUtils";
-import CacheManager, {SubredditCache} from "../Subreddit/SubredditCache";
+import ResourceManager, {SubredditResources} from "../Subreddit/SubredditResources";
+import {ChecksActivityState, TypedActivityStates} from "../Common/interfaces";
+import Author, {AuthorOptions} from "../Author/Author";
 
 export interface RuleOptions {
     name?: string;
-    authors?: AuthorOptions;
+    authorIs?: AuthorOptions;
+    itemIs?: TypedActivityStates;
     logger: Logger
     subredditName: string;
 }
@@ -28,69 +30,101 @@ export interface RuleResult extends ResultContext {
     triggered: (boolean | null)
 }
 
+export interface RuleSetResult {
+    results: RuleResult[],
+    condition: 'OR' | 'AND',
+    triggered: boolean
+}
+
+export const isRuleSetResult = (obj: any): obj is RuleSetResult => {
+    return typeof obj === 'object' && Array.isArray(obj.results) && obj.condition !== undefined && obj.triggered !== undefined;
+}
+
 export interface Triggerable {
-    run(item: Comment | Submission, existingResults: RuleResult[]): Promise<[(boolean | null), RuleResult[]]>;
+    run(item: Comment | Submission, existingResults: RuleResult[]): Promise<[(boolean | null), RuleResult?]>;
 }
 
 export abstract class Rule implements IRule, Triggerable {
     name: string;
     logger: Logger
-    authors: AuthorOptions;
-    cache: SubredditCache;
+    authorIs: AuthorOptions;
+    itemIs: TypedActivityStates;
+    resources: SubredditResources;
 
     constructor(options: RuleOptions) {
         const {
             name = this.getKind(),
             logger,
-            authors: {
+            authorIs: {
                 include = [],
                 exclude = [],
             } = {},
+            itemIs = [],
             subredditName,
         } = options;
         this.name = name;
-        this.cache = CacheManager.get(subredditName);
+        this.resources = ResourceManager.get(subredditName) as SubredditResources;
 
-        this.authors = {
+        this.authorIs = {
             exclude: exclude.map(x => new Author(x)),
             include: include.map(x => new Author(x)),
         }
 
-        const ruleUniqueName = this.name === undefined ? this.getKind() : `${this.getKind()} - ${this.name}`;
-        this.logger = logger.child({labels: ['Rule',`${ruleUniqueName}`]}, mergeArr);
+        this.itemIs = itemIs;
+
+        this.logger = logger.child({labels: [`Rule ${this.getRuleUniqueName()}`]}, mergeArr);
     }
 
-    async run(item: Comment | Submission, existingResults: RuleResult[] = []): Promise<[(boolean | null), RuleResult[]]> {
-        const existingResult = findResultByPremise(this.getPremise(), existingResults);
-        if (existingResult) {
-            this.logger.debug(`Returning existing result of ${existingResult.triggered ? '✔️' : '❌'}`);
-            return Promise.resolve([existingResult.triggered, [{...existingResult, name: this.name}]]);
-        }
-        if (this.authors.include !== undefined && this.authors.include.length > 0) {
-            for (const auth of this.authors.include) {
-                if (await this.cache.testAuthorCriteria(item, auth)) {
-                    return this.process(item);
-                }
+    async run(item: Comment | Submission, existingResults: RuleResult[] = []): Promise<[(boolean | null), RuleResult]> {
+        try {
+            const existingResult = findResultByPremise(this.getPremise(), existingResults);
+            if (existingResult) {
+                this.logger.debug(`Returning existing result of ${existingResult.triggered ? '✔️' : '❌'}`);
+                return Promise.resolve([existingResult.triggered, {...existingResult, name: this.name}]);
             }
-            this.logger.verbose('Inclusive author criteria not matched, rule running skipped');
-            return Promise.resolve([false, [this.getResult(null, {result: 'Inclusive author criteria not matched, rule running skipped'})]]);
-        }
-        if (this.authors.exclude !== undefined && this.authors.exclude.length > 0) {
-            for (const auth of this.authors.exclude) {
-                if (await this.cache.testAuthorCriteria(item, auth, false)) {
-                    return this.process(item);
-                }
+            const itemPass = await this.resources.testItemCriteria(item, this.itemIs);
+            if (!itemPass) {
+                this.logger.verbose(`(Skipped) Item did not pass 'itemIs' test`);
+                return Promise.resolve([null, this.getResult(null, {result: `Item did not pass 'itemIs' test`})]);
             }
-            this.logger.verbose('Exclusive author criteria not matched, rule running skipped');
-            return Promise.resolve([false, [this.getResult(null, {result: 'Exclusive author criteria not matched, rule running skipped'})]]);
+            if (this.authorIs.include !== undefined && this.authorIs.include.length > 0) {
+                for (const auth of this.authorIs.include) {
+                    if (await this.resources.testAuthorCriteria(item, auth)) {
+                        return this.process(item);
+                    }
+                }
+                this.logger.verbose('(Skipped) Inclusive author criteria not matched');
+                return Promise.resolve([null, this.getResult(null, {result: 'Inclusive author criteria not matched'})]);
+            }
+            if (this.authorIs.exclude !== undefined && this.authorIs.exclude.length > 0) {
+                for (const auth of this.authorIs.exclude) {
+                    if (await this.resources.testAuthorCriteria(item, auth, false)) {
+                        return this.process(item);
+                    }
+                }
+                this.logger.verbose('(Skipped) Exclusive author criteria not matched');
+                return Promise.resolve([null, this.getResult(null, {result: 'Exclusive author criteria not matched'})]);
+            }
+        } catch (err) {
+            this.logger.error('Error occurred during Rule pre-process checks');
+            throw err;
+        }
+        try {
+            return this.process(item);
+        } catch (err) {
+            this.logger.error('Error occurred while processing rule');
+            throw err;
         }
-        return this.process(item);
     }
 
-    protected abstract process(item: Comment | Submission): Promise<[boolean, RuleResult[]]>;
+    protected abstract process(item: Comment | Submission): Promise<[boolean, RuleResult]>;
 
     abstract getKind(): string;
 
+    getRuleUniqueName() {
+        return this.name === undefined ? this.getKind() : `${this.getKind()} - ${this.name}`;
+    }
+
     protected abstract getSpecificPremise(): object;
 
     getPremise(): RulePremise {
@@ -98,7 +132,8 @@ export abstract class Rule implements IRule, Triggerable {
         return {
             kind: this.getKind(),
             config: {
-                authors: this.authors,
+                authorIs: this.authorIs,
+                itemIs: this.itemIs,
                 ...config,
             },
         };
@@ -114,69 +149,72 @@ export abstract class Rule implements IRule, Triggerable {
     }
 }
 
-export class Author implements AuthorCriteria {
-    name?: string[];
-    flairCssClass?: string[];
-    flairText?: string[];
-    isMod?: boolean;
-
-    constructor(options: AuthorCriteria) {
-        this.name = options.name;
-        this.flairCssClass = options.flairCssClass;
-        this.flairText = options.flairText;
-        this.isMod = options.isMod;
-    }
-}
-
-/**
- * If present then these Author criteria are checked before running the rule. If criteria fails then the rule is skipped.
- * @minProperties 1
- * @additionalProperties false
- * @TJS-type object
- * */
-export interface AuthorOptions {
+export interface UserNoteCriteria {
     /**
-     * Will "pass" if any set of AuthorCriteria passes
+     * User Note type key to search for
+     * @examples ["spamwarn"]
      * */
-    include?: AuthorCriteria[];
+    type: string;
     /**
-     * Only runs if include is not present. Will "pass" if any of set of the AuthorCriteria does not pass
-     * */
-    exclude?: AuthorCriteria[];
-}
-
-/**
- * Criteria with which to test against the author of an Activity. The outcome of the test is based on:
- *
- * 1. All present properties passing and
- * 2. If a property is a list then any value from the list matching
- *
- * @minProperties 1
- * @additionalProperties false
- * */
-export interface AuthorCriteria {
-    /**
-     * A list of reddit usernames (case-insensitive) to match against. Do not include the "u/" prefix
+     * Number of occurrences of this type. Ignored if `search` is `current`
      *
-     *  EX to match against /u/FoxxMD and /u/AnotherUser use ["FoxxMD","AnotherUser"]
-     * @examples ["FoxxMD","AnotherUser"]
+     * A string containing a comparison operator and/or a value to compare number of occurrences against
+     *
+     * The syntax is `(< OR > OR <= OR >=) <number>[percent sign] [ascending|descending]`
+     *
+     * @examples [">= 1"]
+     * @default ">= 1"
+     * @pattern ^\s*(?<opStr>>|>=|<|<=)\s*(?<value>\d+)\s*(?<percent>%?)\s*(?<extra>asc.*|desc.*)*$
      * */
-    name?: string[],
+    count?: string;
+
     /**
-     * A list of (user) flair css class values from the subreddit to match against
+     * How to test the notes for this Author:
+     *
+     * ### current
+     *
+     * Only the most recent note is checked for `type`
+     *
+     * ### total
+     *
+     * The `count` comparison of `type` must be found within all notes
+     *
+     * * EX `count: > 3`   => Must have more than 3 notes of `type`, total
+     * * EX `count: <= 25%` => Must have 25% or less of notes of `type`, total
+     *
+     * ### consecutive
+     *
+     * The `count` **number** of `type` notes must be found in a row.
+     *
+     * You may also specify the time-based order in which to search the notes by specifying `ascending (asc)` or `descending (desc)` in the `count` value. Default is `descending`
+     *
+     * * EX `count: >= 3` => Must have 3 or more notes of `type` consecutively, in descending order
+     * * EX `count: < 2`  => Must have less than 2 notes of `type` consecutively, in descending order
+     * * EX `count: > 4 asc` => Must have greater than 4 notes of `type` consecutively, in ascending order
+     *
+     * @examples ["current"]
+     * @default current
      * */
-    flairCssClass?: string[],
-    /**
-     * A list of (user) flair text values from the subreddit to match against
-     * */
-    flairText?: string[],
-    /**
-     * Is the author a moderator?
-     * */
-    isMod?: boolean,
+    search?: 'current' | 'consecutive' | 'total'
 }
 
-export interface IRule {
+/**
+ * A duration and how to compare it against a value
+ *
+ * The syntax is `(< OR > OR <= OR >=) <number> <unit>` EX `> 100 days`, `<= 2 months`
+ *
+ * * EX `> 100 days` => Passes if the date being compared is before 100 days ago
+ * * EX `<= 2 months` => Passes if the date being compared is after or equal to 2 months
+ *
+ * Unit must be one of [DayJS Duration units](https://day.js.org/docs/en/durations/creating)
+ *
+ * [See] https://regexr.com/609n8 for example
+ *
+ * @pattern ^\s*(>|>=|<|<=)\s*(\d+)\s*(days|weeks|months|years|hours|minutes|seconds|milliseconds)\s*$
+ * */
+export type DurationComparor = string;
+
+export interface IRule extends ChecksActivityState {
     /**
      * An optional, but highly recommended, friendly name for this rule. If not present will default to `kind`.
      *
@@ -184,18 +222,27 @@ export interface IRule {
      *
      * name is used to reference Rule result data during Action content templating. See CommentAction or ReportAction for more details.
      * @pattern ^[a-zA-Z]([\w -]*[\w])?$
+     * @examples ["myNewRule"]
      * */
     name?: string
     /**
      * If present then these Author criteria are checked before running the rule. If criteria fails then the rule is skipped.
      * */
-    authors?: AuthorOptions
+    authorIs?: AuthorOptions
+    /**
+     * A list of criteria to test the state of the `Activity` against before running the Rule.
+     *
+     * If any set of criteria passes the Rule will be run. If the criteria fails then the Rule is skipped.
+     *
+     * */
+    itemIs?: TypedActivityStates
 }
 
 export interface RuleJSONConfig extends IRule {
     /**
      * The kind of rule to run
+     * @examples ["recentActivity", "repeatActivity", "author", "attribution", "history"]
      */
-    kind: 'recentActivity' | 'repeatActivity' | 'author' | 'attribution' | 'history'
+    kind: 'recentActivity' | 'repeatActivity' | 'author' | 'attribution' | 'history' | 'regex'
 }
 

src/Schema/Action.json

@@ -1,24 +1,346 @@
 {
     "$schema": "http://json-schema.org/draft-07/schema#",
+    "definitions": {
+        "AuthorCriteria": {
+            "additionalProperties": false,
+            "description": "Criteria with which to test against the author of an Activity. The outcome of the test is based on:\n\n1. All present properties passing and\n2. If a property is a list then any value from the list matching",
+            "examples": [
+                {
+                    "flairText": [
+                        "Contributor",
+                        "Veteran"
+                    ],
+                    "isMod": true,
+                    "name": [
+                        "FoxxMD",
+                        "AnotherUser"
+                    ]
+                }
+            ],
+            "minProperties": 1,
+            "properties": {
+                "age": {
+                    "description": "Test the age of the Author's account (when it was created) against this comparison\n\nThe syntax is `(< OR > OR <= OR >=) <number> <unit>`\n\n* EX `> 100 days` => Passes if Author's account is older than 100 days\n* EX `<= 2 months` => Passes if Author's account is younger than or equal to 2 months\n\nUnit must be one of [DayJS Duration units](https://day.js.org/docs/en/durations/creating)\n\n[See] https://regexr.com/609n8 for example",
+                    "pattern": "^\\s*(?<opStr>>|>=|<|<=)\\s*(?<time>\\d+)\\s*(?<unit>days?|weeks?|months?|years?|hours?|minutes?|seconds?|milliseconds?)\\s*$",
+                    "type": "string"
+                },
+                "commentKarma": {
+                    "description": "A string containing a comparison operator and a value to compare karma against\n\nThe syntax is `(< OR > OR <= OR >=) <number>[percent sign]`\n\n* EX `> 100`  => greater than 100 comment karma\n* EX `<= 75%` => comment karma is less than or equal to 75% of **all karma**",
+                    "pattern": "^\\s*(>|>=|<|<=)\\s*(\\d+)\\s*(%?)(.*)$",
+                    "type": "string"
+                },
+                "flairCssClass": {
+                    "description": "A list of (user) flair css class values from the subreddit to match against",
+                    "examples": [
+                        "red"
+                    ],
+                    "items": {
+                        "type": "string"
+                    },
+                    "type": "array"
+                },
+                "flairText": {
+                    "description": "A list of (user) flair text values from the subreddit to match against",
+                    "examples": [
+                        "Approved"
+                    ],
+                    "items": {
+                        "type": "string"
+                    },
+                    "type": "array"
+                },
+                "isMod": {
+                    "description": "Is the author a moderator?",
+                    "type": "boolean"
+                },
+                "linkKarma": {
+                    "description": "A string containing a comparison operator and a value to compare link karma against\n\nThe syntax is `(< OR > OR <= OR >=) <number>[percent sign]`\n\n* EX `> 100`  => greater than 100 link karma\n* EX `<= 75%` => link karma is less than or equal to 75% of **all karma**",
+                    "pattern": "^\\s*(>|>=|<|<=)\\s*(\\d+)\\s*(%?)(.*)$",
+                    "type": "string"
+                },
+                "name": {
+                    "description": "A list of reddit usernames (case-insensitive) to match against. Do not include the \"u/\" prefix\n\n EX to match against /u/FoxxMD and /u/AnotherUser use [\"FoxxMD\",\"AnotherUser\"]",
+                    "examples": [
+                        "FoxxMD",
+                        "AnotherUser"
+                    ],
+                    "items": {
+                        "type": "string"
+                    },
+                    "type": "array"
+                },
+                "totalKarma": {
+                    "description": "A string containing a comparison operator and a value to compare against\n\nThe syntax is `(< OR > OR <= OR >=) <number>`\n\n* EX `> 100`  => greater than 100",
+                    "pattern": "^\\s*(>|>=|<|<=)\\s*(\\d+)\\s*(%?)(.*)$",
+                    "type": "string"
+                },
+                "userNotes": {
+                    "description": "A list of UserNote properties to check against the User Notes attached to this Author in this Subreddit (must have Toolbox enabled and used User Notes at least once)",
+                    "items": {
+                        "$ref": "#/definitions/UserNoteCriteria"
+                    },
+                    "type": "array"
+                },
+                "verified": {
+                    "description": "Does Author's account have a verified email?",
+                    "type": "boolean"
+                }
+            },
+            "type": "object"
+        },
+        "AuthorOptions": {
+            "description": "If present then these Author criteria are checked before running the rule. If criteria fails then the rule is skipped.",
+            "examples": [
+                {
+                    "include": [
+                        {
+                            "flairText": [
+                                "Contributor",
+                                "Veteran"
+                            ]
+                        },
+                        {
+                            "isMod": true
+                        }
+                    ]
+                }
+            ],
+            "properties": {
+                "exclude": {
+                    "description": "Only runs if `include` is not present. Will \"pass\" if any of set of the AuthorCriteria **does not** pass",
+                    "items": {
+                        "$ref": "#/definitions/AuthorCriteria"
+                    },
+                    "type": "array"
+                },
+                "include": {
+                    "description": "Will \"pass\" if any set of AuthorCriteria passes",
+                    "items": {
+                        "$ref": "#/definitions/AuthorCriteria"
+                    },
+                    "type": "array"
+                }
+            },
+            "type": "object"
+        },
+        "CommentState": {
+            "description": "Different attributes a `Comment` can be in. Only include a property if you want to check it.",
+            "examples": [
+                {
+                    "op": true,
+                    "removed": false
+                }
+            ],
+            "properties": {
+                "approved": {
+                    "type": "boolean"
+                },
+                "deleted": {
+                    "type": "boolean"
+                },
+                "distinguished": {
+                    "type": "boolean"
+                },
+                "filtered": {
+                    "type": "boolean"
+                },
+                "locked": {
+                    "type": "boolean"
+                },
+                "op": {
+                    "description": "Is this Comment Author also the Author of the Submission this comment is in?",
+                    "type": "boolean"
+                },
+                "removed": {
+                    "type": "boolean"
+                },
+                "spam": {
+                    "type": "boolean"
+                },
+                "stickied": {
+                    "type": "boolean"
+                },
+                "submissionState": {
+                    "description": "A list of SubmissionState attributes to test the Submission this comment is in",
+                    "items": {
+                        "$ref": "#/definitions/SubmissionState"
+                    },
+                    "type": "array"
+                }
+            },
+            "type": "object"
+        },
+        "SubmissionState": {
+            "description": "Different attributes a `Submission` can be in. Only include a property if you want to check it.",
+            "examples": [
+                {
+                    "over_18": true,
+                    "removed": false
+                }
+            ],
+            "properties": {
+                "approved": {
+                    "type": "boolean"
+                },
+                "deleted": {
+                    "type": "boolean"
+                },
+                "distinguished": {
+                    "type": "boolean"
+                },
+                "filtered": {
+                    "type": "boolean"
+                },
+                "is_self": {
+                    "type": "boolean"
+                },
+                "link_flair_css_class": {
+                    "type": "string"
+                },
+                "link_flair_text": {
+                    "type": "string"
+                },
+                "locked": {
+                    "type": "boolean"
+                },
+                "over_18": {
+                    "description": "NSFW",
+                    "type": "boolean"
+                },
+                "pinned": {
+                    "type": "boolean"
+                },
+                "removed": {
+                    "type": "boolean"
+                },
+                "spam": {
+                    "type": "boolean"
+                },
+                "spoiler": {
+                    "type": "boolean"
+                },
+                "stickied": {
+                    "type": "boolean"
+                },
+                "title": {
+                    "description": "A valid regular expression to match against the title of the submission",
+                    "type": "string"
+                }
+            },
+            "type": "object"
+        },
+        "UserNoteCriteria": {
+            "properties": {
+                "count": {
+                    "default": ">= 1",
+                    "description": "Number of occurrences of this type. Ignored if `search` is `current`\n\nA string containing a comparison operator and/or a value to compare number of occurrences against\n\nThe syntax is `(< OR > OR <= OR >=) <number>[percent sign] [ascending|descending]`",
+                    "examples": [
+                        ">= 1"
+                    ],
+                    "pattern": "^\\s*(?<opStr>>|>=|<|<=)\\s*(?<value>\\d+)\\s*(?<percent>%?)\\s*(?<extra>asc.*|desc.*)*$",
+                    "type": "string"
+                },
+                "search": {
+                    "default": "current",
+                    "description": "How to test the notes for this Author:\n\n### current\n\nOnly the most recent note is checked for `type`\n\n### total\n\nThe `count` comparison of `type` must be found within all notes\n\n* EX `count: > 3`   => Must have more than 3 notes of `type`, total\n* EX `count: <= 25%` => Must have 25% or less of notes of `type`, total\n\n### consecutive\n\nThe `count` **number** of `type` notes must be found in a row.\n\nYou may also specify the time-based order in which to search the notes by specifying `ascending (asc)` or `descending (desc)` in the `count` value. Default is `descending`\n\n* EX `count: >= 3` => Must have 3 or more notes of `type` consecutively, in descending order\n* EX `count: < 2`  => Must have less than 2 notes of `type` consecutively, in descending order\n* EX `count: > 4 asc` => Must have greater than 4 notes of `type` consecutively, in ascending order",
+                    "enum": [
+                        "consecutive",
+                        "current",
+                        "total"
+                    ],
+                    "examples": [
+                        "current"
+                    ],
+                    "type": "string"
+                },
+                "type": {
+                    "description": "User Note type key to search for",
+                    "examples": [
+                        "spamwarn"
+                    ],
+                    "type": "string"
+                }
+            },
+            "required": [
+                "type"
+            ],
+            "type": "object"
+        }
+    },
     "properties": {
+        "authorIs": {
+            "$ref": "#/definitions/AuthorOptions",
+            "description": "If present then these Author criteria are checked before running the Action. If criteria fails then the Action is not run.",
+            "examples": [
+                {
+                    "include": [
+                        {
+                            "flairText": [
+                                "Contributor",
+                                "Veteran"
+                            ]
+                        },
+                        {
+                            "isMod": true
+                        }
+                    ]
+                }
+            ]
+        },
         "dryRun": {
             "default": false,
             "description": "If `true` the Action will not make the API request to Reddit to perform its action.",
+            "examples": [
+                false,
+                true
+            ],
             "type": "boolean"
         },
+        "enable": {
+            "default": true,
+            "description": "If set to `false` the Action will not be run",
+            "examples": [
+                true
+            ],
+            "type": "boolean"
+        },
+        "itemIs": {
+            "anyOf": [
+                {
+                    "items": {
+                        "$ref": "#/definitions/SubmissionState"
+                    },
+                    "type": "array"
+                },
+                {
+                    "items": {
+                        "$ref": "#/definitions/CommentState"
+                    },
+                    "type": "array"
+                }
+            ],
+            "description": "A list of criteria to test the state of the `Activity` against before running the Action.\n\nIf any set of criteria passes the Action will be run."
+        },
         "kind": {
             "description": "The type of action that will be performed",
             "enum": [
+                "approve",
+                "ban",
                 "comment",
                 "flair",
                 "lock",
+                "message",
                 "remove",
-                "report"
+                "report",
+                "usernote"
             ],
             "type": "string"
         },
         "name": {
             "description": "An optional, but highly recommended, friendly name for this Action. If not present will default to `kind`.\n\nCan only contain letters, numbers, underscore, spaces, and dashes",
+            "examples": [
+                "myDescriptiveAction"
+            ],
             "pattern": "^[a-zA-Z]([\\w -]*[\\w])?$",
             "type": "string"
         }

src/Schema/OperatorConfig.json

@@ -0,0 +1,555 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "definitions": {
+        "CacheOptions": {
+            "description": "Configure granular settings for a cache provider with this object",
+            "properties": {
+                "auth_pass": {
+                    "description": "(`redis`) the authentication passphrase (if enabled)",
+                    "type": "string"
+                },
+                "db": {
+                    "default": 0,
+                    "description": "(`redis`) the db number to use",
+                    "examples": [
+                        0
+                    ],
+                    "type": "number"
+                },
+                "host": {
+                    "default": "localhost",
+                    "description": "(`redis`) hostname",
+                    "examples": [
+                        "localhost"
+                    ],
+                    "type": "string"
+                },
+                "max": {
+                    "default": 500,
+                    "description": "(`memory`) The maximum number of keys (unique cache calls) to store in cache\n\nWhen the maximum number of keys is reached the cache will being dropping the [least-recently-used](https://github.com/isaacs/node-lru-cache) key to keep the cache at `max` size.\n\nThis will determine roughly how large in **RAM** each `memory` cache can be, based on how large your `window` criteria are. Consider this example:\n\n* all `window` criteria in a subreddit's rules are `\"window\": 100`\n* `\"max\": 500`\n* Maximum size of **each** memory cache will be `500 x 100 activities = 50,000 activities`\n  * So the shared cache would be max 50k activities and\n  * Every additional private cache (when a subreddit configures their cache separately) will also be max 50k activities",
+                    "examples": [
+                        500
+                    ],
+                    "type": "number"
+                },
+                "port": {
+                    "default": 6379,
+                    "description": "(`redis`) port to connect on",
+                    "examples": [
+                        6379
+                    ],
+                    "type": "number"
+                },
+                "store": {
+                    "$ref": "#/definitions/CacheProvider"
+                },
+                "ttl": {
+                    "default": 60,
+                    "description": "The default TTL, in seconds, for the cache provider.\n\nCan mostly be ignored since TTLs are defined for each cache object",
+                    "examples": [
+                        60
+                    ],
+                    "type": "number"
+                }
+            },
+            "required": [
+                "store"
+            ],
+            "type": "object"
+        },
+        "CacheProvider": {
+            "description": "Available cache providers",
+            "enum": [
+                "memory",
+                "none",
+                "redis"
+            ],
+            "type": "string"
+        },
+        "DiscordProviderConfig": {
+            "properties": {
+                "name": {
+                    "type": "string"
+                },
+                "type": {
+                    "enum": [
+                        "discord"
+                    ],
+                    "type": "string"
+                },
+                "url": {
+                    "type": "string"
+                }
+            },
+            "required": [
+                "name",
+                "type",
+                "url"
+            ],
+            "type": "object"
+        },
+        "NotificationConfig": {
+            "properties": {
+                "events": {
+                    "items": {
+                        "anyOf": [
+                            {
+                                "$ref": "#/definitions/NotificationEventConfig"
+                            },
+                            {
+                                "items": {
+                                    "enum": [
+                                        "configUpdated",
+                                        "eventActioned",
+                                        "pollingError",
+                                        "runStateChanged"
+                                    ],
+                                    "type": "string"
+                                },
+                                "type": "array"
+                            }
+                        ]
+                    },
+                    "type": "array"
+                },
+                "providers": {
+                    "description": "A list of notification providers (Discord, etc..) to configure. Each object in the list is one provider. Multiple of the same provider can be provided but must have different names",
+                    "items": {
+                        "$ref": "#/definitions/DiscordProviderConfig"
+                    },
+                    "type": "array"
+                }
+            },
+            "required": [
+                "events",
+                "providers"
+            ],
+            "type": "object"
+        },
+        "NotificationEventConfig": {
+            "properties": {
+                "providers": {
+                    "items": {
+                        "type": "string"
+                    },
+                    "type": "array"
+                },
+                "types": {
+                    "items": {
+                        "enum": [
+                            "configUpdated",
+                            "eventActioned",
+                            "pollingError",
+                            "runStateChanged"
+                        ],
+                        "type": "string"
+                    },
+                    "type": "array"
+                }
+            },
+            "required": [
+                "providers",
+                "types"
+            ],
+            "type": "object"
+        },
+        "PollingDefaults": {
+            "properties": {
+                "delayUntil": {
+                    "description": "Delay processing Activity until it is `N` seconds old\n\nUseful if there are other bots that may process an Activity and you want this bot to run first/last/etc.\n\nIf the Activity is already `N` seconds old when it is initially retrieved no refresh of the Activity occurs (no API request is made) and it is immediately processed.",
+                    "type": "number"
+                },
+                "interval": {
+                    "default": 30,
+                    "description": "Amount of time, in seconds, to wait between requests",
+                    "examples": [
+                        30
+                    ],
+                    "type": "number"
+                },
+                "limit": {
+                    "default": 50,
+                    "description": "The maximum number of Activities to get on every request",
+                    "examples": [
+                        50
+                    ],
+                    "type": "number"
+                }
+            },
+            "type": "object"
+        }
+    },
+    "description": "Configuration for application-level settings IE for running the bot instance\n\n* To load a JSON configuration **from the command line** use the `-c` cli argument EX: `node src/index.js -c /path/to/JSON/config.json`\n* To load a JSON configuration **using an environmental variable** use `OPERATOR_CONFIG` EX: `OPERATOR_CONFIG=/path/to/JSON/config.json`",
+    "properties": {
+        "api": {
+            "description": "Settings related to managing heavy API usage.",
+            "properties": {
+                "hardLimit": {
+                    "default": 50,
+                    "description": "When `api limit remaining` reaches this number the application will pause all event polling until the api limit is reset.",
+                    "examples": [
+                        50
+                    ],
+                    "type": "number"
+                },
+                "softLimit": {
+                    "default": 250,
+                    "description": "When `api limit remaining` reaches this number the application will attempt to put heavy-usage subreddits in a **slow mode** where activity processed is slowed to one every 1.5 seconds until the api limit is reset.",
+                    "examples": [
+                        250
+                    ],
+                    "type": "number"
+                }
+            },
+            "type": "object"
+        },
+        "caching": {
+            "description": "Settings to configure the default caching behavior for each suberddit",
+            "properties": {
+                "authorTTL": {
+                    "default": 60,
+                    "description": "Amount of time, in seconds, author activity history (Comments/Submission) should be cached\n\n* ENV => `AUTHOR_TTL`\n* ARG => `--authorTTL <sec>`",
+                    "examples": [
+                        60
+                    ],
+                    "type": "number"
+                },
+                "commentTTL": {
+                    "default": 60,
+                    "description": "Amount of time, in seconds, a comment should be cached",
+                    "examples": [
+                        60
+                    ],
+                    "type": "number"
+                },
+                "filterCriteriaTTL": {
+                    "default": 60,
+                    "description": "Amount of time, in seconds, to cache filter criteria results (`authorIs` and `itemIs` results)\n\nThis is especially useful if when polling high-volume comments and your checks rely on author/item filters",
+                    "examples": [
+                        60
+                    ],
+                    "type": "number"
+                },
+                "provider": {
+                    "anyOf": [
+                        {
+                            "$ref": "#/definitions/CacheOptions"
+                        },
+                        {
+                            "enum": [
+                                "memory",
+                                "none",
+                                "redis"
+                            ],
+                            "type": "string"
+                        }
+                    ],
+                    "description": "The cache provider and, optionally, a custom configuration for that provider\n\nIf not present or `null` provider will be `memory`.\n\nTo specify another `provider` but use its default configuration set this property to a string of one of the available providers: `memory`, `redis`, or `none`"
+                },
+                "submissionTTL": {
+                    "default": 60,
+                    "description": "Amount of time, in seconds, a submission should be cached",
+                    "examples": [
+                        60
+                    ],
+                    "type": "number"
+                },
+                "userNotesTTL": {
+                    "default": 300,
+                    "description": "Amount of time, in seconds, [Toolbox User Notes](https://www.reddit.com/r/toolbox/wiki/docs/usernotes) should be cached",
+                    "examples": [
+                        300
+                    ],
+                    "type": "number"
+                },
+                "wikiTTL": {
+                    "default": 300,
+                    "description": "Amount of time, in seconds, wiki content pages should be cached",
+                    "examples": [
+                        300
+                    ],
+                    "type": "number"
+                }
+            },
+            "type": "object"
+        },
+        "credentials": {
+            "description": "The credentials required for the bot to interact with Reddit's API\n\n**Note:** Only `clientId` and `clientSecret` are required for initial setup (to use the oauth helper) **but ALL are required to properly run the bot.**",
+            "properties": {
+                "accessToken": {
+                    "description": "Access token retrieved from authenticating an account with your Reddit Application\n\n* ENV => `ACCESS_TOKEN`\n* ARG => `--accessToken <token>`",
+                    "examples": [
+                        "p75_1c467b2"
+                    ],
+                    "type": "string"
+                },
+                "clientId": {
+                    "description": "Client ID for your Reddit application\n\n* ENV => `CLIENT_ID`\n* ARG => `--clientId <id>`",
+                    "examples": [
+                        "f4b4df1c7b2"
+                    ],
+                    "type": "string"
+                },
+                "clientSecret": {
+                    "description": "Client Secret for your Reddit application\n\n* ENV => `CLIENT_SECRET`\n* ARG => `--clientSecret <id>`",
+                    "examples": [
+                        "34v5q1c56ub"
+                    ],
+                    "type": "string"
+                },
+                "redirectUri": {
+                    "description": "Redirect URI for your Reddit application\n\nOnly required if running ContextMod with a web interface (and after using oauth helper)\n\n* ENV => `REDIRECT_URI`\n* ARG => `--redirectUri <uri>`",
+                    "examples": [
+                        "http://localhost:8085"
+                    ],
+                    "format": "uri",
+                    "type": "string"
+                },
+                "refreshToken": {
+                    "description": "Refresh token retrieved from authenticating an account with your Reddit Application\n\n* ENV => `REFRESH_TOKEN`\n* ARG => `--refreshToken <token>`",
+                    "examples": [
+                        "34_f1w1v4"
+                    ],
+                    "type": "string"
+                }
+            },
+            "type": "object"
+        },
+        "logging": {
+            "description": "Settings to configure global logging defaults",
+            "properties": {
+                "level": {
+                    "default": "verbose",
+                    "description": "The minimum log level to output. The log level set will output logs at its level **and all levels above it:**\n\n * `error`\n * `warn`\n * `info`\n * `verbose`\n * `debug`\n\n Note: `verbose` will display *a lot* of information on the status/result of run rules/checks/actions etc. which is very useful for testing configurations. Once your bot is stable changing the level to `info` will reduce log noise.\n\n * ENV => `LOG_LEVEL`\n * ARG => `--logLevel <level>`",
+                    "enum": [
+                        "debug",
+                        "error",
+                        "info",
+                        "verbose",
+                        "warn"
+                    ],
+                    "examples": [
+                        "verbose"
+                    ],
+                    "type": "string"
+                },
+                "path": {
+                    "description": "The absolute path to a directory where rotating log files should be stored.\n\n* If not present or `null` no log files will be created\n* If `true` logs will be stored at `[working directory]/logs`\n\n* ENV => `LOG_DIR`\n* ARG => `--logDir [dir]`",
+                    "examples": [
+                        "/var/log/contextmod"
+                    ],
+                    "type": "string"
+                }
+            },
+            "type": "object"
+        },
+        "notifications": {
+            "$ref": "#/definitions/NotificationConfig",
+            "description": "Settings to configure 3rd party notifications for when ContextMod behavior occurs"
+        },
+        "operator": {
+            "description": "Settings related to the user(s) running this ContextMod instance and information on the bot",
+            "properties": {
+                "botName": {
+                    "description": "The name to use when identifying the bot. Defaults to name of the authenticated Reddit account IE `u/yourBotAccount`",
+                    "examples": [
+                        "u/yourBotAccount"
+                    ],
+                    "type": "string"
+                },
+                "display": {
+                    "description": "A **public** name to display to users of the web interface. Use this to help moderators using your bot identify who is the operator in case they need to contact you.\n\nLeave undefined for no public name to be displayed.\n\n* ENV => `OPERATOR_DISPLAY`\n* ARG => `--operatorDisplay <name>`",
+                    "examples": [
+                        "Moderators of r/MySubreddit"
+                    ],
+                    "type": "string"
+                },
+                "name": {
+                    "anyOf": [
+                        {
+                            "items": {
+                                "type": "string"
+                            },
+                            "type": "array"
+                        },
+                        {
+                            "type": "string"
+                        }
+                    ],
+                    "description": "The name, or names, of the Reddit accounts, without prefix, that the operators of this bot uses.\n\nThis is used for showing more information in the web interface IE show all logs/subreddits if even not a moderator.\n\nEX -- User is /u/FoxxMD then `\"name\": [\"FoxxMD\"]`\n\n* ENV => `OPERATOR` (if list, comma-delimited)\n* ARG => `--operator <name...>`",
+                    "examples": [
+                        [
+                            "FoxxMD",
+                            "AnotherUser"
+                        ]
+                    ]
+                }
+            },
+            "type": "object"
+        },
+        "polling": {
+            "allOf": [
+                {
+                    "$ref": "#/definitions/PollingDefaults"
+                },
+                {
+                    "properties": {
+                        "sharedMod": {
+                            "default": false,
+                            "description": "If set to `true` all subreddits polling unmoderated/modqueue with default polling settings will share a request to \"r/mod\"\notherwise each subreddit will poll its own mod view\n\n* ENV => `SHARE_MOD`\n* ARG => `--shareMod`",
+                            "type": "boolean"
+                        }
+                    },
+                    "type": "object"
+                }
+            ],
+            "description": "Settings related to default polling configurations for subreddits"
+        },
+        "queue": {
+            "description": "Settings related to default configurations for queue behavior for subreddits",
+            "properties": {
+                "maxWorkers": {
+                    "default": 1,
+                    "description": "Set the number of maximum concurrent workers any subreddit can use.\n\nSubreddits may define their own number of max workers in their config but the application will never allow any subreddit's max workers to be larger than the operator\n\nNOTE: Do not increase this unless you are certain you know what you are doing! The default is suitable for the majority of use cases.",
+                    "examples": [
+                        1
+                    ],
+                    "type": "number"
+                }
+            },
+            "type": "object"
+        },
+        "snoowrap": {
+            "description": "Settings to control some [Snoowrap](https://github.com/not-an-aardvark/snoowrap) behavior",
+            "properties": {
+                "debug": {
+                    "description": "Manually set the debug status for snoowrap\n\nWhen snoowrap has `debug: true` it will log the http status response of reddit api requests to at the `debug` level\n\n* Set to `true` to always output\n* Set to `false` to never output\n\nIf not present or `null` will be set based on `logLevel`\n\n* ENV => `SNOO_DEBUG`\n* ARG => `--snooDebug`",
+                    "type": "boolean"
+                },
+                "proxy": {
+                    "description": "Proxy all requests to Reddit's API through this endpoint\n\n* ENV => `PROXY`\n* ARG => `--proxy <proxyEndpoint>`",
+                    "examples": [
+                        "http://localhost:4443"
+                    ],
+                    "type": "string"
+                }
+            },
+            "type": "object"
+        },
+        "subreddits": {
+            "description": "Settings related to bot behavior for subreddits it is managing",
+            "properties": {
+                "dryRun": {
+                    "default": false,
+                    "description": "If `true` then all subreddits will run in dry run mode, overriding configurations\n\n* ENV => `DRYRUN`\n* ARG => `--dryRun`",
+                    "examples": [
+                        false
+                    ],
+                    "type": "boolean"
+                },
+                "heartbeatInterval": {
+                    "default": 300,
+                    "description": "Interval, in seconds, to perform application heartbeat\n\nOn heartbeat the application does several things:\n\n* Log output with current api rate remaining and other statistics\n* Tries to retrieve and parse configurations for any subreddits with invalid configuration state\n* Restarts any bots stopped/paused due to polling issues, general errors, or invalid configs (if new config is valid)\n\n* ENV => `HEARTBEAT`\n* ARG => `--heartbeat <sec>`",
+                    "examples": [
+                        300
+                    ],
+                    "type": "number"
+                },
+                "names": {
+                    "description": "Names of subreddits for bot to run on\n\nIf not present or `null` bot will run on all subreddits it is a moderator of\n\n* ENV => `SUBREDDITS` (comma-separated)\n* ARG => `--subreddits <list...>`",
+                    "examples": [
+                        [
+                            "mealtimevideos",
+                            "programminghumor"
+                        ]
+                    ],
+                    "items": {
+                        "type": "string"
+                    },
+                    "type": "array"
+                },
+                "wikiConfig": {
+                    "default": "botconfig/contextbot",
+                    "description": "The default relative url to the ContextMod wiki page EX `https://reddit.com/r/subreddit/wiki/<path>`\n\n* ENV => `WIKI_CONFIG`\n* ARG => `--wikiConfig <path>`",
+                    "examples": [
+                        "botconfig/contextbot"
+                    ],
+                    "type": "string"
+                }
+            },
+            "type": "object"
+        },
+        "web": {
+            "description": "Settings for the web interface",
+            "properties": {
+                "enabled": {
+                    "default": true,
+                    "description": "Whether the web server interface should be started\n\nIn most cases this does not need to be specified as the application will automatically detect if it is possible to start it --\nuse this to specify \"cli only\" behavior if you encounter errors with port/address or are paranoid\n\n* ENV => `WEB`\n* ARG => `node src/index.js run [interface]` -- interface can be `web` or `cli`",
+                    "type": "boolean"
+                },
+                "logLevel": {
+                    "description": "The default log level to filter to in the web interface\n\nIf not specified or `null` will be same as global `logLevel`",
+                    "enum": [
+                        "debug",
+                        "error",
+                        "info",
+                        "verbose",
+                        "warn"
+                    ],
+                    "type": "string"
+                },
+                "maxLogs": {
+                    "default": 200,
+                    "description": "Maximum number of log statements to keep in memory for each subreddit",
+                    "examples": [
+                        200
+                    ],
+                    "type": "number"
+                },
+                "port": {
+                    "default": 8085,
+                    "description": "The port for the web interface\n\n* ENV => `PORT`\n* ARG => `--port <number>`",
+                    "examples": [
+                        8085
+                    ],
+                    "type": "number"
+                },
+                "session": {
+                    "description": "Settings to configure the behavior of user sessions -- the session is what the web interface uses to identify logged in users.",
+                    "properties": {
+                        "provider": {
+                            "anyOf": [
+                                {
+                                    "$ref": "#/definitions/CacheOptions"
+                                },
+                                {
+                                    "enum": [
+                                        "memory",
+                                        "redis"
+                                    ],
+                                    "type": "string"
+                                }
+                            ],
+                            "default": "memory",
+                            "description": "The cache provider to use.\n\nThe default should be sufficient for almost all use cases",
+                            "examples": [
+                                "memory"
+                            ]
+                        },
+                        "secret": {
+                            "description": "The secret value used to encrypt session data\n\nIf provider is persistent (redis) specifying a value here will ensure sessions are valid between application restarts\n\nWhen not present or `null` a random string is generated on application start",
+                            "examples": [
+                                "definitelyARandomString"
+                            ],
+                            "type": "string"
+                        }
+                    },
+                    "type": "object"
+                }
+            },
+            "type": "object"
+        }
+    },
+    "type": "object"
+}
+

src/Server/helper.ts

@@ -0,0 +1,85 @@
+import {addAsync, Router} from '@awaitjs/express';
+import express from 'express';
+import Snoowrap from "snoowrap";
+import {permissions} from "../util";
+import {getLogger} from "../Utils/loggerFactory";
+import {OperatorConfig} from "../Common/interfaces";
+
+const app = addAsync(express());
+const router = Router();
+app.set('views', `${__dirname}/views`);
+app.set('view engine', 'ejs');
+
+app.use(router);
+
+const helperServer = async function (options: OperatorConfig) {
+    let rUri: string;
+
+    const {
+        credentials: {
+            clientId,
+            clientSecret,
+            redirectUri
+        },
+        web: {
+            port
+        }
+    } = options;
+
+    const server = await app.listen(port);
+    const logger = getLogger(options);
+    logger.info(`Helper UI started: http://localhost:${port}`);
+    app.getAsync('/', async (req, res) => {
+        res.render('helper', {
+            redirectUri
+        });
+    });
+
+    app.getAsync('/auth', async (req, res) => {
+        rUri = req.query.redirect as string;
+        let permissionsList = permissions;
+
+        const includeWikiEdit = (req.query.wikiEdit as any).toString() === "1";
+        if (!includeWikiEdit) {
+            permissionsList = permissionsList.filter(x => x !== 'wikiedit');
+        }
+        const authUrl = Snoowrap.getAuthUrl({
+            clientId,
+            scope: permissionsList,
+            redirectUri: rUri as string,
+            permanent: true,
+        });
+        return res.redirect(authUrl);
+    });
+
+    app.getAsync(/.*callback$/, async (req, res) => {
+        const {error, code} = req.query as any;
+        if (error !== undefined) {
+            let errContent: string;
+            switch (error) {
+                case 'access_denied':
+                    errContent = 'You must <b>Allow</b> this application to connect in order to proceed.';
+                    break;
+                default:
+                    errContent = error;
+            }
+            return res.render('error', {error: errContent, });
+        }
+        const client = await Snoowrap.fromAuthCode({
+            userAgent: `web:contextBot:web`,
+            clientId,
+            clientSecret,
+            redirectUri: rUri,
+            code: code as string,
+        });
+        // @ts-ignore
+        const user = await client.getMe();
+
+        res.render('callback', {
+            accessToken: client.accessToken,
+            refreshToken: client.refreshToken,
+        });
+    });
+}
+
+export default helperServer;