Skip to content
Say hello to Doorman, your made-to-fit community manager. Simple API, feature-rich plugins, and more.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
assets
components
config
docs
lib
plugins
public/assets
services
test
.coveralls.yml
.gitignore
.travis.yml
LICENSE
README.md
doorman.js
jsdoc.json
package.json

README.md

Doorman

Build Status Coverage Status Total Contributors

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):

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.

You can’t perform that action at this time.