Creating a Koa.js app

A convenience method for creating a Koa app augmented with the ability to define add-ons is provided by the following boilerplate setup:

var ack = require('ac-koa').require('hipchat');
var pkg = require('./package.json');
var app = ack(pkg);

In this example, the app object is the configured Koa application, ready to define one or more add-ons in following steps.

Add-on definition

Add-ons can be defined on the app object in two ways:

Pass a full or partial descriptor literal to to the app.addon() method

app.addon({
  // optional descriptor metas here (taken from package.json when not overridden here)
  capabilities: {
    // standard HipChat capabilities descriptor body
  }
});

When using this style, you're responsible for manually configuring routes to handle any webhooks defined.

Pass nothing to app.addon() and use the more concise descriptor builder API

If you pass nothing to the addon method, a descriptor builder API will be applied that allows critical sections of the descriptor to be defined with builder methods. This is particularly useful for conveniently defining webhook handlers while also building the descriptor.

For example, the following defines a fully functional descriptor while also associating a webhook handler:

var addon = app.addon()
  .hipchat()
  .allowRoom(true)
  .scopes('send_notification');

addon.webhook('room_message', /^\/hello$/, function *() {
  yield this.roomClient.sendNotification('Hi, ' + this.sender.name + '!');
});

Multiple add-on support

More than one add-on can be mounted at a time in a single Koa app by giving each a unique mount scope. For example:

var addon1 = app.addon('addon1')
  .hipchat()
  .key('addon1-key')
  .name('Addon 1')
  .allowRoom(true)
  .scopes('send_notification');

var addon2 = app.addon('addon2')
  .hipchat()
  .key('addon2-key')
  .name('Addon 2')
  .allowRoom(true)
  .scopes('send_notification');

The scope given to each addon() method is automatically used for both data partitioning and route disambiguation.