Slack-utils NPM

slack-utils

This is a collection of various slack-api related scripts that I've written. Published as an npm module.

Development is done in coffeescript, but that is not a dependency for usage.

Installation

npm install --save slack-utils

Usage

Currently, utils consists of 2 modules: api and rtm. All possible methods are demonstrated below:

// Initialize api
// You can leave either as undefined if you don't want to use those features
api = require('slack-utils/api')('SLACK_API_TOKEN', 'INCOMING_HOOK_URL')

// channel is the channel name (such as general)
// nick is the username of the user to send the message to
// username is the username used by the webhook
api.postMessage('message', 'channel', 'username')

// The icon can be set as final parameter in various ways (optional)
api.postMessage('message', 'channel', 'username', ":ghost:")
api.postMessage('message', 'channel', 'username', "ghost") // this is converted to an emoji
api.postMessage('message', 'channel', 'username', "https://www.gravatar.com/avatar/e") // A valid image url

// Sendmessage currently does not support icons
api.sendMessage('message', 'nick', 'username')

info = api.UserInfoById('U025QJXBB') //returns cached user info
info = api.UserInfoByName('nemo')    //returns cached user info

// Initialize rtm
// You can get an API_TOKEN from https://api.slack.com/web for your personal account
// Or by creating a bot user at https://my.slack.com/services/new/bot
rtm = require('slack-utils/rtm')(API_TOKEN);

rtm.on('event', function(msg){
  // Do whatever you want with the data
  // msg.type will be same as event name
})

A list of events emitted can be found at https://api.slack.com/rtm
Few extra events are emitted as well:
- connect: When the websocket connects to the RTM server
- ready: When Slack responds to our RTM connection
- error: In case of an error in the websocket connection
- active: When a user's presence changes to active
- away: When a user's presence changes to away
- *: Emitted for all slack-events (not for 3 low-level events: connect, ready, and error)

Differences

This is not a one-to-one mapping for the various slack APIs. This is done for a reason:

Simplicity. You should be able to use various APIs without having to worry about things like userid translation
Other 1-1 APIs already exist
We add extra events and methods to simplify usage. For eg, we include a sendMessage and a postMessage method to send a direct message or a public message. This is hidden inside the incoming webhook docs, but we surface it as 2 method calls.
The aim is to make your code more terse and readable.

Development

Code is written in coffeescript
Editorconfig is used for indentation guidelines
Coffeescript is pushed to github
Testing is done via mocha, and travis
npm test works
Only javascript is pushed to npm
Coffeescript is a development dependency, so its not installed in production
ws and request are used for websocket and http API usage
You will need to set an API token in environment to run tests
You can put one in a .env file with the following contents:
- API_TOKEN=xoxb-4059276139-J54hTmEgjJGWa0FAKE_TOKEN

Help Needed

Since I am pretty used to the slack API by now, I am very much comfortable writing this.
I'd love if people used this for their services.
Please file an issue if you have a usecase not covered by this.
I am not used to writing javascript APIs, so I'd love to hear thoughts on how this can be improved
Documentation. I'd get around to it soon, but I'd love a helping hand. Will probably use docco.