zboox-addon

Library to create ZBox Now! addons for Express

Installation

npm install --save zbox-addon

In your project root create a file called zbox-addon.json with the following schema:

{
  "key": "hello-addon",
  "name": "Hello!",
  "description": "My very first ZBox Addon",
  "vendor": {
    "name": "Elias Nahum",
    "icon_url": "{{localBaseUrl}}/images/logo.png"
  },
  "price": {
    "currency": "CLP",
    "value": 0
  },
  "links": {
    "published_url": "{{localBaseUrl}}/published",
    "descriptor_url": "{{localBaseUrl}}/zbox-addon.json",
    "homepage_url": "http://localhost:3000"
  },
  "installable": {
    "installed_url": "{{localBaseUrl}}/installed",
    "uninstalled_url": "{{localBaseUrl}}/uninstalled",
    "config_url": "{{localBaseUrl}}/config",
    "allow_global": true,
    "allow_channel": false
  },
  "webhook": {
    "enable_incoming": true,
    "outgoing": [
      {
        "key": "hello_webhook_1",
        "callback_urls": [
          "{{localBaseUrl}}/webhook"
        ],
        "triggers": [
          "hello:"
        ]
      }
    ]
  }
}

And then another file called config.json like this one:

{
  "development": {
    "baseUrl": "http://localhost:3000"
  },
  "production": {
    "baseUrl": "http://myaddon.com"
  }
}

If your zbox-addon.json file has the {{localBaseUrl}} pattern it will be replace by the baseUrl in config.json at runtime with the one that corresponds to the environment.

Usage

Addon

To start using the addon, in your express app.

var express = require('express');
var zbox = require('zbox-addon').addon;

var app = express();
var addon = zbox(app, opts, logger, callback);

• app mandatory express app
• opts options to configure the addon
• logger optional logger to use (winston used by default if no logger is supplied)
• callback function to call when the addon has finish configuration

Options

log_to_filesystem(bool)

when using the default logger you can log entries to a log file in the logs directory in your project root. The logs will auto rotate each day with the following format: filename-yyyy-MM-dd.log

log_filename(string)

the name of the file to use with the default logger if none is supplied zboxaddon will be used.

Methods

context() Middleware to be use in conjuction with express routes.

In case of a webhook the req.hook object will be set with the following values:

{
    "token": "use this to validate the webhook",
    "team_id": "the id of the team from where the webhook was initiated",
    "channel_id": "the id of the channel from where the webhook was initiated",
    "channel_name": "the name of the channel from where the webhook was initiated",
    "datetime": "Date and time when the webhook was initiated",
    "user_id": "the id of the user who initiated the webhook",
    "username": "the username of the user who initiated the webhook",
    "message": "the text written by the user"
}

For the configuration route req.context is set with the following values:

{
    "team_id": "The id of the team that is configuring the addon",
    "team_name": "The name of the team"
}

Events

The addon will return some important information through events

• published

  Once your addon has been published on ZBox Now! the published event will be triggered with the following arguments:

  • client_id(string)
  • client_secret(string)

  IMPORTANT: This credentials should be save in case you later need to make api calls.

  Note: client_secret cannot be recovered if you lose it.

• installed

  Once your addon has been installed by a team in ZBox Now! the installed event will be triggered with the following arguments:

  • team(object)
    • id(string): the Id of the team that installed the addon
    • name(string): the name of the team that installed the addon
  • incoming(object)
    • token the token to use when sending messages to ZBox Now! to this team
  • outgoing(array of objects): one for each webhook registered
    • key(string): the key used in the zbox-addon.json to configure the webhooks
    • token(string): the token to validate a webhook request.

  Note: The team name is latter use with every api call so you probably want to save this values somewhere like in your Database.

• uninstalled

  If your addon is uninstalled by a team in ZBox Now! the uninstalled event will be triggered with the following arguments:

  • team_id(string)

  Note: Use this to remove all the necesary information for a team. Once the team has uninstalled your addon, you will no longer be able to use the API, you won't be able to send messages and your webhooks won't be triggered.

API

The API is used to get information from ZBox Now!

In order to use the API you need to register the addon, client_id and client_secret

var api = require('zbox-addon').api;

var zboxApi = api(addon, opts);

Options

• client_id(string)
• client_secret(string)
• url(string): use this option when you want to use the API from a URL different than ZBox Now! production server.

Methods

• sendMessage(opts, callback)

  This method lets you send a message to ZBox Now! using your incoming webhook token for one of the teams. if you define a callback(err) it will be called after the message has been sent or an error has ocurred.

  • opts
    • message(string): the message to send markdown is available.
    • channel_name(string): the name of the channel that will recieve the message (if none is supplied then the message will be sent to the default channel town-square)

• prepare(message)

  Prepares the message to be sent to ZBox Now!

  for example:

  return res.json(zboxApi.prepare(message));

• getChannels(teamName, callback)

  Returns all the existing channels for a team to the callback function as an array of objects argument.

  • teamName(string): the name of the team

  The returned array of objects to the callback have the following structure:

  [
      {
          "id": "the id of the channel",
          "type": "the type of channel values can be 'channel' or 'group'",
          "display_name": "The name of the channel the way it is shown to the users",
          "name": "The actual name of the channel (use this with sendMessage)"
      }
  ]

• getUsers(teamName, callback)

  Returns all the existing users for a team to the callback function as an array of objects argument.

  • teamName(string): the name of the team

    The returned array of objects to the callback have the following structure:

    [
        {
            "id": "the id of the user",
            "username": "the username of the user",
            "email": "The email address of the user",
            "nickname": "(only if is set)",
            "firs_name": "(only if is set)",
            "last_name": "(only if is set)",
            "locale": "The user preferred language"
        }
    ]

License

(The MIT License)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.