README.md

Doorman

Doorman is a friendly, automated helper for managers of large online communities. Simple to install and easy to configure, Doorman can welcome new users, guide them through onboarding flows, and help keep track of important projects and events using a robust-plugin API.

Quick Start

1. Fork (optional) and clone: git clone https://github.com/FabricLabs/doorman.git
2. Run cp config/index.json.example config/index.json & add your auth tokens
3. Run npm install
4. Run npm start

Services

Doorman comes pre-configured with support for multiple chat platforms, including Slack, Discord, and Matrix. Adding support for additional services is easy — inspect the lib/service.js prototype for a list of required methods. Feel free to submit a Pull Request to add support for your favorite services!

Plugins

Doorman behaviors range from simple triggers (commands prefixed with ! located anywhere within a message) to complex applications which communicate through a simple message-passing API. The trigger prefix is configurable using the trigger keyword in the configuration file.

Plugins are automatically loaded when included in config/index.json, under the "plugins" section, or manually by calling doorman.use(). Doorman will look first in the ./plugins folder for the named plugin (most useful for simple prototyping), then will attempt to load from NPM using the doorman-* naming pattern. Plugins may be published to the NPM registry and installed via npm install as usual.

Official Plugins

List of external plugins for you to include with your installation (if you wish):

• xkcd => adds the !xkcd command
• wikipedia => adds the !wiki command
• urbandictionary => adds the !urban command
• dictionary => adds the !define command
• dice => adds the !roll command
• cocktail-lookup => adds the !cocktail command
• beer-lookup => adds the !brew command
• translator => adds translation commands
• misc => adds misc commands that don't fall into other categories
• admin => adds administrative commands
• catfact => spits out a random cat fact
• insult => spits out a random PG insult
• interstellafact => spits out a random fact about Interstella 5555
• topologyfact => spits out a random topology fact
• choicemaker => makes a choice for you, based on given inputs
• 8ball => ask the magic 8ball something!
• smifffact => spits out a random fact about Will Smith
• dogfact => spits out a random dog fact
• chucknorrisfact => spits out a random fact about Chuck Norris
• mathfact => spits out a random math fact
• yearfact => spits out a random year fact
• datefact => spits out a random date fact
• remaeusfact => spits out a random fact about Remaeus

Simple Plugins

Ping-Pong Example Plugin, ./plugins/ping.json

{
  "ping": "Pong!"
}

To use this plugin, add ping to your configuration file and Doorman will respond to any messages that include !ping with a simple Pong! response.

Complex Plugins

In addition to simple !triggers, Doorman can call functions to compute responses, or even instantiate external applications for managing long-running processes.

Function Call Example Plugin, ./plugins/erm.js

const erm = require('erm');
const plugin = {
  erm: function (msg) {
    return erm(msg);
  }
};

module.exports = plugin;

Instantiated Example Plugin

function MyPlugin (config) {
  // config will be passed from `./config/index.json` based on the plugin name
  this.start();
}

MyPlugin.prototype.start = function () {
  console.log('Hello, world!');
};

module.exports = MyPlugin;

Manually Loading Plugins

To load the plugin, simply call doorman.use() on the plugin you wish to add. Multiple !triggers can be added, each as key => value mappings provided by the plugin.

const config = require('./config');
const plugin = { fancy: 'Mmm, fancy!' };

const Doorman = require('doorman');
const doorman = new Doorman(config);

doorman.use(plugin);
doorman.start();

Message Passing API

Doorman emits events like any other EventEmitter, using a simple router for distinguishing between messages, users, and channels on various services. This allows Doorman to stay connected to multiple networks simultaneously — a feature we rely on in our flagship project, Fabric!

General Message Format

Identifiers

Doorman uses the Fabric Messaging Format to uniquely identify objects within the system. Each object has an id field, which usually takes the following format:

:service/:collection/:identifier

For example, a user event might emit the following object:

{
  "id": "slack/users/U09HF4JLV",
  "@data": {
    "id": "U09HF4JLV"
  }
}

Users (the user event)

Channels (the channel event)

Messages (the message event)

State Management (the patch event)

Configuration

Configuring Doorman will typically require the creation of a "bot" user on the platform of choice, and the use of a security token to authenticate requests.

Matrix

Register a user for your bot, then collect the "Access Token" from the user's settings — you will need to use the "click to reveal" feature to display the token.

Place the token into config/index.json under the matrix index, and specify user and authority:

{
  "matrix": {
    "token": "place-the-token-here",
    "user": "@doorman:ericmartindale.com",
    "authority": "https://matrix.verse.pub"
  }
}

Slack

In your team's workspace, browse to "Apps", "Custom Integrations", "Bots", and finally "New configuration". Place the "API Token" into config/index.json:

{
  "slack": {
    "token": "xoxb-0000000000000-somelongstring..."
  }
}

Discord

@naterchrdsn will need to fill this out. :)

Documentation

Documentation can be generated by running npm run make:docs — this will output an HTML-formatted copy of the API to docs/, which can be served with (if installed!) http-server docs or simply opened in your browser.