node-flint v4.8.1

node-flint (v4)

Bot SDK for Node JS

News

10/25/19 Support for Adaptive Cards:

• Cisco recently introduced support for Adaptive Cards in the Webex Teams. Bots can send cards, using the new attachment attribute of the message object. Cards are useful as an alternative to text messages and files in order to display or collect complex bits of information. Cards can be sent by passing an object to the bot.say() method that includes a valid attachment. To process user input to cards, apps must implement a flint.on('attachmentaction', ..) function. For more details see the adaptive-card-example

6/21/19 Deploying behind a firewall:

• Cisco has recently introduced support in the Webex Javascript SDK which allows applications to register to receive the message, membership, and room events via a socket instead of via wehbhoks. This allows applications to be deployed behind firewalls and removes the requirement that webex bots and integrations must expose a public IP address to receive events. To take advantage of this in your flint applications simply remove the webhookUrl field from the configuration object passed to the flint constructor. If this field is not set, flint will register to listen for these events instead of creating webhooks.

6/21/18 IMPORTANT:

• On August 31st, 2018 all bots with the sparkbot.io domain name will be renamed with a webex.bot domain. Today in flint, the code compares the bot's email with the trigger email to filter out messages from itself. If this code is running on August 31st the bot will start responding to its own messages. Please update to Flint v4.7.x as soon as possible to avoid interruption.

3/19/18 IMPORTANT:

• Note that Flint v4 is still using the node-sparky library version 3.x. However the repo for node-sparky is now on version 4 which has some major differences. This misalignment between Flint and Sparky version will be fixed with the release of Flint v5. In the short term if you are accessing the spark object directly from Flint via flint.spark be sure to use the documentation for node-sparky 3.x.

See CHANGELOG.md for details on changes to versions of Flint.

Contents

• Installation
  • Via Git
  • Via NPM
  • Example Template Using Express
• Overview
• Authentication
• Storage
• Bot Accounts

Installation

Via Git

mkdir myproj
cd myproj
git clone https://github.com/nmarus/flint
npm install ./flint

Via NPM

mkdir myproj
cd myproj
npm install node-flint

Example Template Using Express

var Flint = require('node-flint');
var webhook = require('node-flint/webhook');
var express = require('express');
var bodyParser = require('body-parser');
var app = express();
app.use(bodyParser.json());

// flint options
var config = {
  webhookUrl: 'http://myserver.com/flint',
  token: 'Tm90aGluZyB0byBzZWUgaGVyZS4uLiBNb3ZlIGFsb25nLi4u',
  port: 80
};

// init flint
var flint = new Flint(config);
flint.start();

// say hello
flint.hears('/hello', function(bot, trigger) {
  bot.say('Hello %s!', trigger.personDisplayName);
});

// define express path for incoming webhooks
// This is not necessary if webhookUrl is not set in the config
app.post('/flint', webhook(flint));

// start express server
// This is not necessary if webhookUrl is not set in the config
// unless the bot uses express for other reasons
var server = app.listen(config.port, function () {
  flint.debug('Flint listening on port %s', config.port);
});

// gracefully shutdown (ctrl-c)
process.on('SIGINT', function() {
  flint.debug('stoppping...');
  server.close();   // remove if not using webhooks and express
  flint.stop().then(function() {
    process.exit();
  });
});

Restify Example

Overview

Most of Flint's functionality is based around the flint.hears function. This defines the phrase or pattern the bot is listening for and what actions to take when that phrase or pattern is matched. The flint.hears function gets a callback than includes two objects. The bot object, and the trigger object.

Flint generates a bot object instance of the Bot class for each room the Spark account Flint is running under. The bot object instance tracks the specifics about the room it is running in and is passed to the "hears" command callback when a phrase is heard.

Flint also generates a trigger object based on the person and room that the flint.hears function was triggered.

A simple example of a flint.hears() function setup:

flint.hears(phrase, function(bot, trigger) {
  bot.<command>
    .then(function(returnedValue) {
      // do something with returned value
    })
    .catch(function(err) {
      // handle errors
    });
});

• phrase : This can be either a string or a regex pattern. If a string, the string is matched against the first word in the room message. message. If a regex pattern is used, it is matched against the entire message text.
• bot : The bot object that is used to execute commands when the phrase is triggered.
• bot.<command> : The Bot method to execute.
• then : Node JS Promise keyword that invokes additional logic once the previous command is executed.
• catch : handle errors that happen at either the original command or in any of the chained 'then' functions.
• trigger : The object that describes the details around what triggered the phrase.
• commands : The commands that are ran when the phrase is heard.

Authentication

The token used to authenticate Flint to the Spark (now Webex) API is passed as part of the options used when instantiating the Flint class. To change or update the token, use the Flint#setSparkToken() method.

Example:

var newToken = 'Tm90aGluZyB0byBzZWUgaGVyZS4uLiBNb3ZlIGFsb25nLi4u';

flint.setSparkToken(newToken)
.then(function(token) {
  console.log('token updated to: ' + token);
});

Storage

The storage system used in flint is a simple key/value store and resolves around these 3 methods:

• bot.store(key, value) - Store a value to a bot instance where 'key' is a string and 'value' is a boolean, number, string, array, or object. This does not not support functions or any non serializable data. Returns the a promise with the value.
• bot.recall(key) - Recall a value by 'key' from a bot instance. Returns a resolved promise with the value or a rejected promise if not found.
• bot.forget([key]) - Forget (remove) value(s) from a bot instance where 'key' is an optional property that when defined, removes the specific key, and when undefined, removes all keys. Returns a resolved promise if deleted or not found.

When a bot despawns (removed from room), the key/value store for that bot instance will automatically be removed from the store. Flint currently has an in-memory store and a Redis based store. By default, the in-memory store is used. Other backend stores are possible by replicating any one of the built-in storage modules and passing it to the flint.storeageDriver() method. See docs for store, recall, forget for more details.

Example:

var redisDriver = require('node-flint/storage/redis');
flint.storageDriver(redisDriver('redis://localhost'));

Bot Accounts

When using "Bot Accounts" the major differences are:

• Webhooks for message:created only trigger when the Bot is mentioned by name
• Unable to read messages in rooms using the Spark (now Webex) API

Differences with trigger.args using Flint with a "Bot Account":

The trigger.args array is a shortcut in processing the trigger.text string. It consists of an array of the words that are in the trigger.message string split by one or more spaces. Punctation is included if there is no space between the symbol and the word. With bot accounts, this behaves a bit differently.

• If defining a flint.hears() using a string (not regex), trigger.args is a filtered array of words from the message that begins after the first match of bot mention.

• If defining a flint.hears() using regex, the trigger.args array is the entire message.

Flint Reference

Classes

Objects

Events

Flint

Kind: global class
Properties

• Flint
  • new Flint(options)
  • .options : object
  • .setSparkToken(token) ⇒ Promise.<String>
  • .stop() ⇒ Promise.<Boolean>
  • .start() ⇒ Promise.<Boolean>
  • .restart() ⇒ Promise.<Boolean>
  • .getMessage(messageId) ⇒ Promise.<Message>
  • .getFiles(messageId) ⇒ Promise.<Array>
  • .hears(phrase, action, [helpText], [preference]) ⇒ String
  • .clearHears(id) ⇒ null
  • .showHelp([header], [footer]) ⇒ String
  • .setAuthorizer(Action) ⇒ Boolean
  • .clearAuthorizer() ⇒ null
  • .storageDriver(Driver) ⇒ null
  • .use(path) ⇒ Boolean

new Flint(options)

Creates an instance of Flint.

Example

var options = {
  webhookUrl: 'http://myserver.com/flint',
  token: 'Tm90aGluZyB0byBzZWUgaGVyZS4uLiBNb3ZlIGFsb25nLi4u'
};
var flint = new Flint(options);

flint.options : object

Options Object

Kind: instance namespace of Flint
Properties

flint.setSparkToken(token) ⇒ Promise.<String>

Tests, and then sets a new Spark Token.

Kind: instance method of Flint

Example

flint.setSparkToken('Tm90aGluZyB0byBzZWUgaGVyZS4uLiBNb3ZlIGFsb25nLi4u')
  .then(function(token) {
     console.log('token updated to: ' + token);
  });

flint.stop() ⇒ Promise.<Boolean>

Stop Flint.

Kind: instance method of Flint
Example

flint.stop();

flint.start() ⇒ Promise.<Boolean>

Start Flint.

Kind: instance method of Flint
Example

flint.start();

flint.restart() ⇒ Promise.<Boolean>

Restart Flint.

Kind: instance method of Flint
Example

flint.restart();

flint.getMessage(messageId) ⇒ Promise.<Message>

Get Message Object by ID

Kind: instance method of Flint

flint.getFiles(messageId) ⇒ Promise.<Array>

Get Files from Message Object by ID

Kind: instance method of Flint

flint.hears(phrase, action, helpText, preference) ⇒ String

Add action to be performed when bot hears a phrase.

Kind: instance method of Flint

Example

// using a string to match first word and defines help text
flint.hears('/say', function(bot, trigger, id) {
  bot.say(trigger.args.slice(1, trigger.arges.length - 1));
}, '/say <greeting> - Responds with a greeting');

Example

// using regex to match across entire message
flint.hears(/(^| )beer( |.|$)/i, function(bot, trigger, id) {
  bot.say('Enjoy a beer, %s! 🍻', trigger.personDisplayName);
});

flint.clearHears(id) ⇒ null

Remove a "flint.hears()" entry.

Kind: instance method of Flint

Example

// using a string to match first word and defines help text
var hearsHello = flint.hears('/flint', function(bot, trigger, id) {
  bot.say('Hello %s!', trigger.personDisplayName);
});
flint.clearHears(hearsHello);

flint.showHelp(header, footer) ⇒ String

Display help for registered Flint Commands.

Kind: instance method of Flint

Example

flint.hears('/help', function(bot, trigger, id) {
  bot.say(flint.showHelp());
});

flint.setAuthorizer(Action) ⇒ Boolean

Attaches authorizer function.

Kind: instance method of Flint

Example

function myAuthorizer(bot, trigger, id) {
  if(trigger.personEmail === 'john@test.com') {
    return true;
  }
  else if(trigger.personDomain === 'test.com') {
    return true;
  }
  else {
    return false;
  }
}
flint.setAuthorizer(myAuthorizer);

flint.clearAuthorizer() ⇒ null

Removes authorizer function.

Kind: instance method of Flint
Example

flint.clearAuthorizer();

flint.storageDriver(Driver) ⇒ null

Defines storage backend.

Kind: instance method of Flint

Example

// define memory store (default if not specified)
flint.storageDriver(new MemStore());

flint.use(path) ⇒ Boolean

Load a Plugin from a external file.

Kind: instance method of Flint

Example

flint.use('events.js');

Example

// events.js
module.exports = function(flint) {
  flint.on('spawn', function(bot) {
    console.log('new bot spawned in room: %s', bot.myroom.title);
  });
  flint.on('despawn', function(bot) {
    console.log('bot despawned in room: %s', bot.myroom.title);
  });
  flint.on('messageCreated', function(message, bot) {
    console.log('"%s" said "%s" in room "%s"', message.personEmail, message.text, bot.myroom.title);
  });
};

Bot

Kind: global class
Properties

• Bot
  • new Bot(flint)
  • .exit() ⇒ Promise.<Boolean>
  • .add(email(s), [moderator]) ⇒ Promise.<Array>
  • .remove(email(s)) ⇒ Promise.<Array>
  • .getModerators() ⇒ Promise.<Array>
  • .newRoom(name, emails) ⇒ Promise.<Bot>
  • .newTeamRoom(name, emails) ⇒ Promise.<Bot>
  • .moderateRoom() ⇒ Promise.<Bot>
  • .unmoderateRoom() ⇒ Promise.<Bot>
  • .moderatorSet(email(s)) ⇒ Promise.<Bot>
  • .moderatorClear(email(s)) ⇒ Promise.<Bot>
  • .implode() ⇒ Promise.<Boolean>
  • .say([format], message) ⇒ Promise.<Message>
  • .dm(email, [format], message) ⇒ Promise.<Message>
  • .uploadStream(filename, stream) ⇒ Promise.<Message>
  • .upload(filepath) ⇒ Promise.<Message>
  • .censor(messageId) ⇒ Promise.<Message>
  • .roomRename(title) ⇒ Promise.<Room>
  • .getMessages(count) ⇒ Promise.<Array>
  • .store(key, value) ⇒ Promise.<String> | Promise.<Number> | Promise.<Boolean> | Promise.<Array> | Promise.<Object>
  • .recall([key]) ⇒ Promise.<String> | Promise.<Number> | Promise.<Boolean> | Promise.<Array> | Promise.<Object>
  • .forget([key]) ⇒ Promise.<String> | Promise.<Number> | Promise.<Boolean> | Promise.<Array> | Promise.<Object>

new Bot(flint)

Creates a Bot instance that is then attached to a Spark Room.

bot.exit() ⇒ Promise.<Boolean>

Instructs Bot to exit from room.

Kind: instance method of Bot
Example

bot.exit();

bot.add(email(s), moderator) ⇒ Promise.<Array>

Instructs Bot to add person(s) to room.

Kind: instance method of Bot
Returns: Promise.<Array> - Array of emails added

Example

// add one person to room by email
bot.add('john@test.com');

Example

// add one person as moderator to room by email
bot.add('john@test.com', true)
  .catch(function(err) {
    // log error if unsuccessful
    console.log(err.message);
  });

Example

// add 3 people to room by email
bot.add(['john@test.com', 'jane@test.com', 'bill@test.com']);

bot.remove(email(s)) ⇒ Promise.<Array>

Instructs Bot to remove person from room.

Kind: instance method of Bot
Returns: Promise.<Array> - Array of emails removed

Example

// remove one person to room by email
bot.remove('john@test.com');

Example

// remove 3 people from room by email
bot.remove(['john@test.com', 'jane@test.com', 'bill@test.com']);

bot.getModerators() ⇒ Promise.<Array>

Get room moderators.

Kind: instance method of Bot
Example

bot.getModerators()
  .then(function(moderators) {
    console.log(moderators);
  });

bot.newRoom(name, emails) ⇒ Promise.<Bot>

Create new room with people by email

Kind: instance method of Bot

bot.newTeamRoom(name, emails) ⇒ Promise.<Bot>

Create new Team Room

Kind: instance method of Bot

bot.moderateRoom() ⇒ Promise.<Bot>

Enable Room Moderation.Enable.

Kind: instance method of Bot
Example

bot.moderateRoom()
  .then(function(err) {
    console.log(err.message)
  });

bot.unmoderateRoom() ⇒ Promise.<Bot>

Disable Room Moderation.

Kind: instance method of Bot
Example

bot.unmoderateRoom()
  .then(function(err) {
    console.log(err.message)
  });

bot.moderatorSet(email(s)) ⇒ Promise.<Bot>

Assign Moderator in Room

Kind: instance method of Bot

Example

bot.moderatorSet('john@test.com')
  .then(function(err) {
    console.log(err.message)
  });

bot.moderatorClear(email(s)) ⇒ Promise.<Bot>

Unassign Moderator in Room

Kind: instance method of Bot

Example

bot.moderatorClear('john@test.com')
  .then(function(err) {
    console.log(err.message)
  });

bot.implode() ⇒ Promise.<Boolean>

Remove a room and all memberships.

Kind: instance method of Bot
Example

flint.hears('/implode', function(bot, trigger) {
  bot.implode();
});

bot.say(format, message) ⇒ Promise.<Message>

Send text with optional file to room.

Kind: instance method of Bot

Example

// Simple example
flint.hears('/hello', function(bot, trigger) {
  bot.say('hello');
});

Example

// Simple example to send message and file
flint.hears('/file', function(bot, trigger) {
  bot.say({text: 'Here is your file!', file: 'http://myurl/file.doc'});
});

Example

// Markdown Method 1 - Define markdown as default
flint.messageFormat = 'markdown';
flint.hears('/hello', function(bot, trigger) {
  bot.say('**hello**, How are you today?');
});

Example

// Markdown Method 2 - Define message format as part of argument string
flint.hears('/hello', function(bot, trigger) {
  bot.say('markdown', '**hello**, How are you today?');
});

Example

// Mardown Method 3 - Use an object (use this method of bot.say() when needing to send a file in the same message as markdown text.
flint.hears('/hello', function(bot, trigger) {
  bot.say({markdown: '*Hello <@personEmail:' + trigger.personEmail + '|' + trigger.personDisplayName + '>*'});
});

bot.dm(email, format, message) ⇒ Promise.<Message>

Send text with optional file in a direct message. This sends a message to a 1:1 room with the user (creates 1:1, if one does not already exist)

Kind: instance method of Bot

Example

// Simple example
flint.hears('/dm', function(bot, trigger) {
  bot.dm('someone@domain.com', 'hello');
});

Example

// Simple example to send message and file
flint.hears('/dm', function(bot, trigger) {
  bot.dm('someone@domain.com', {text: 'Here is your file!', file: 'http://myurl/file.doc'});
});

Example

// Markdown Method 1 - Define markdown as default
flint.messageFormat = 'markdown';
flint.hears('/dm', function(bot, trigger) {
  bot.dm('someone@domain.com', '**hello**, How are you today?');
});

Example

// Markdown Method 2 - Define message format as part of argument string
flint.hears('/dm', function(bot, trigger) {
  bot.dm('someone@domain.com', 'markdown', '**hello**, How are you today?');
});

Example

// Mardown Method 3 - Use an object (use this method of bot.dm() when needing to send a file in the same message as markdown text.
flint.hears('/dm', function(bot, trigger) {
  bot.dm('someone@domain.com', {markdown: '*Hello <@personEmail:' + trigger.personEmail + '|' + trigger.personDisplayName + '>*'});
});

bot.uploadStream(filename, stream) ⇒ Promise.<Message>

Upload a file to a room using a Readable Stream

Kind: instance method of Bot

Example

flint.hears('/file', function(bot, trigger) {

  // define filename used when uploading to room
  var filename = 'test.png';

  // create readable stream
  var stream = fs.createReadStream('/my/file/test.png');

  bot.uploadStream(filename, stream);
});

bot.upload(filepath) ⇒ Promise.<Message>

Upload a file to room.

Kind: instance method of Bot

Example

flint.hears('/file', function(bot, trigger) {
  bot.upload('test.png');
});

bot.censor(messageId) ⇒ Promise.<Message>

Remove Message By Id.

Kind: instance method of Bot

bot.roomRename(title) ⇒ Promise.<Room>

Set Title of Room.

Kind: instance method of Bot

Example

bot.roomRename('My Renamed Room')
  .then(function(err) {
    console.log(err.message)
  });

bot.getMessages(count) ⇒ Promise.<Array>

Get messages from room. Returned data has newest message at bottom.

Kind: instance method of Bot

Example

bot.getMessages(5).then(function(messages) {
  messages.forEach(function(message) {
    // display message text
    if(message.text) {
      console.log(message.text);
    }
  });
});

bot.store(key, value) ⇒ Promise.<String> | Promise.<Number> | Promise.<Boolean> | Promise.<Array> | Promise.<Object>

Store key/value data.

Kind: instance method of Bot

bot.recall(key) ⇒ Promise.<String> | Promise.<Number> | Promise.<Boolean> | Promise.<Array> | Promise.<Object>

Recall value of data stored by 'key'.

Kind: instance method of Bot

bot.forget(key) ⇒ Promise.<String> | Promise.<Number> | Promise.<Boolean> | Promise.<Array> | Promise.<Object>

Forget a key or entire store.

Kind: instance method of Bot

Message : object

Message Object

Kind: global namespace
Properties

File : object

File Object

Kind: global namespace
Properties

Trigger : object

Trigger Object

Kind: global namespace
Properties

"log"

Flint log event.

Kind: event emitted
Properties

"stop"

Flint stop event.

Kind: event emitted
Properties

"start"

Flint start event.

Kind: event emitted
Properties

"initialized"

Flint initialized event.

Kind: event emitted
Properties

"roomLocked"

Room Locked event.

Kind: event emitted
Properties

"roomUnocked"

Room Unocked event.

Kind: event emitted
Properties

"personEnters"

Person Enter Room event.

Kind: event emitted
Properties

"botAddedAsModerator"

Bot Added as Room Moderator.

Kind: event emitted
Properties

"botRemovedAsModerator"

Bot Removed as Room Moderator.

Kind: event emitted
Properties

"personAddedAsModerator"

Person Added as Moderator.

Kind: event emitted
Properties

"personRemovedAsModerator"

Person Removed as Moderator.

Kind: event emitted
Properties

"personExits"

Person Exits Room.

Kind: event emitted
Properties

"mentioned"

Bot Mentioned.

Kind: event emitted
Properties

"message"

Message Recieved.

Kind: event emitted
Properties

"files"

File Recieved.

Kind: event emitted
Properties

"spawn"

Bot Spawned.

Kind: event emitted
Properties

"despawn"

Bot Despawned.

Kind: event emitted
Properties

License

The MIT License (MIT)

Copyright (c) 2016-2017

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.