This package has been deprecated

Author message:

no source, unmaintained

carlos

!! DEPRACTED !!

Carlos, a chat bot for your team.

Carlos is a chat bot with Slack and Twitch integration, it uses pluggable functions as chat commands. It is meant to quicky create chat commands which have functionality attached to it without having any knowledge of an underlying API (but really is just wrapper around wrapper).

Table Of Contents

• Installation
• Example
• Carlos
  • Initialization
  • Properties
  • Methods
  • Events
• Connectors
  • SlackConnector
  • TwitchConnector
  • Creating connectors (TODO)
• Build (TODO)

Installation

npm install carlos

Example

const carlos = require('carlos');
const connector = new carlos.SlackConnector('xoxb-[TOKEN]');
const chatBot = new carlos.Bot(connector, 'carlos');
 
chatBot.on('connected', function() {
    console.log('Bot connected');
});
 
const knockknock = (commandData) => {
    chatBot.reply(commandData.connectorInfo, 'Who is there?');
};
 
const THISISLOUD = (commandData) => {
    chatBot.reply(commandData.connectorInfo, commandData.postCommandText.toUpperCase());
};
 
// Trigger response "Who is there?" to channel with "!carlos knockknock"
chatBot.register('knockknock', knockknock);
 
// Trigger response "SPEAK UP" to channel with "!carlos loud speak up"
chatBot.register('loud', THISISLOUD);
 
chatBot.boot();

How does Carlos work

Carlos responds to commands issued by !name commandName

Initialization

Require the package

const carlos = require('carlos');

Create a connector and initialize your bot

Check "Connectors" for more explanation about the connectors.

A bot-name can only be registered one time, if you try to register a name twice an error will be thrown. Your script will continue but the second one will be ignored.

!! To create your Slack-token, check Slackconnector !!

const connector = new carlos.SlackConnector('xoxb-[TOKEN]');
 
/**
 * @param connector
 * @param string name
 * [@param function(err) handle possible errors while initializing bot ]
 */
const chatBot = new carlos.Bot(connector, 'carlos');
 
const chatBotCarlos = new carlos.Bot(connector, 'carlos', (err) => {
    if(err) {
        console.log('Name probably exists');
        console.log(err.message);
    }
});

Properties

Carlos exposes its connector variable, which grants you access to underlaying API's and functions.

// Slack connector example
console.log(chatBot.connector); // Slack connector
console.log(chatBot.connector.slack); // Slack RTM API
console.log(chatBot.connector.slackWeb); // Slack Web API

Carlos also exposes the name of the instance, this may come in handy for error logging.

// Get name - set connected
chatBot.on('connected', () => {
    console.log(`"${chatBot.name}" is successfully connected.`);
});

Methods

You are able to add commands Carlos should listen to by registering functions, these functions will be given some info (commandData) about the called action. The exposed info in connectorInfo is dependent of the connector.

If you are ready processing the data and have a witty reponse ready you can call chatBot.reply(commandData.connectorInfo, "Response") to respond in the channel where the command occurred.

!! The name and postCommandText that triggered the command will always be included. No matter which connector is used. !!

Create a function

/**
 * @param obj commandData {
 *     name: string commandName,
 *     postCommandText: string commandMessage,
 *     obj connectorInfo {
 *         [message: messageText - part of SlackConnector]
 *         [,user: userID - part of SlackConnector]
 *         [,channel: channelID - part of SlackConnector]
 *     }
 */
const knockknock = (commandData) => {
    chatBot.reply(commandData.connectorInfo, 'Who is there?');
};

Register the function

You can not register a command twice on the same bot. If you do so, an error will be thrown.

/**
 * @param string name of command
 * @param function command function
 * [@param function(err) handle possible errors while registering function]
 */
chatBot.register('knockknock', knockknock);
 
chatBot.register('knockknock', knockknock, (err) => {
    if(err) {
        console.log(err.message) // One 'knockknock'-joke is enough!
    }
});

Get commands

Get an array of the registered commands.

/**
 * @return array commandNames list all the commands
 */
chatBot.getCommands((err, commands) => {
    console.log(commands) // ['knockknock']
});

This command may come in handy to give your team a list of all the registered commands while introducing the bot.

const listCommands = (commandData) => {
    chatBot.getCommands((err, commands) => {
        chatBot.reply(commandData.connectorInfo, commands.join());
    });
};
 
chatBot.register('list', listCommands);
 
chatBot.getCommands((err, commands) => {
    console.log(commands) // ['knockknock', 'list']
});

Individual connectors may also contain functions that can be used as a command.

See "Connectors" for more.

Unregister functions

Just as easy as you registered functions, you can also unregister a function.

/**
 * @param string commandName to unregister
 */
chatBot.unregister('list');
chatBot.getCommands((err, commands) => {
    console.log(commands) // ['knockknock']
});

Booting Carlos

Booting Carlos is the most important, and also easiest, part. This will make sure your bot is connected and listening to possible events.

chatBot.boot();

Events

On connected

chatBot.on('connected', () => {
    console.log('Bot is now connected');
});

On command

The command event will be triggered as soon as Carlos receives an event. By using a switch in this event you can cut out the register middle man. The commandData object is the same as a function gets.

chatBot.on('command', (commandData) => {
    /**
     *  obj commandData {
     *     name: string commandName,
     *     postCommandText: string commandMessage,
     *     obj connectorInfo {
     *         [message: messageText - part of SlackConnector]
     *         [,user: userID - part of SlackConnector]
     *         [,channel: channelID - part of SlackConnector]
     *     }
     */
    const test = () => {
        return "test";
    };
 
    switch(commandData.name) {
        case 'test':
            let response = test();
            chatBot.reply(commandData.connectorInfo, response);
            break;
        case 'loud':
            let response = commandData.postCommandText.toUpperCase();
            chatBot.reply(commandData.connectorInfo, response);
            break;
        case 'list':
            chatBot.getCommands((err, commands) => {
                chatBot.reply(commandData.connectorInfo, commands.join());
            });
            break;
        default:
            console.log('Error: Unknown command.');
    }
});

On error

chatBot.on('error', (err) => {
    console.log(err.message);
});

Error Code	Error Name	Error Description
1	DuplicateBotError	The bot name is already registered.
2	ConnectorError	Something bad is happening in the connector. Orginal error can be found orginalError property.
3	NoCommandError	ChatBot got triggered but no command was issued.
4	UnknownCommandError	ChatBot got triggered but no command was found.
5	DuplicateCommandError	Command is already registered.

Connectors

Out of the box Carlos comes with a SlackConnector and a TwitchConnector, you can write your own connectors if needed for other integrations. See "Creating connectors".

SlackConnector

You can create your token in your Slack Dashboard once you are signed in. The App Directory is found here. More information about Slack bots can be found here.

Initialize

/**
 * @param string your Slack-token
 */
const connector = new carlos.SlackConnector('xoxb-[TOKEN]');

Methods

/**
 * @return array userNames list all users in Slack
 */
connector.getUsers((err, users) => {
    console.log(users) // [Carlos, Name, User]
});
 
/**
 * @return array channelNames list all channels in Slack
 */
connector.getChannels((err, channels) => {
    console.log(channels) // [Random, General]
});
 

TwitchConnector (first-version)

Connect your bot with Twitch chat. It might be good to consider creating a new account for your bot with an appropriate name to avoid confusion. In this case, it is also considered good to grant your bot-user mod rights.

Initialize

const identityTwitch = {
    username: '[YOUR-USER-NAME]',
    password: 'oauth:[YOUR-TOKEN]'
}
const channelsTwitch = ['#[YOUR-USER-NAME]'];
 
/**
 * @param obj identity Your Twitch-identity
 * @param array channels Twitch-channels to join
 */
const connector = new carlos.TwitchConnector(identityTwitch, channelsTwitch);

Creating connectors

TODO:: (See current ones)

Build

TODO:: (Babel)

Future and TODO's

• Create more connectors.
• Tests.
• (...)