slack-bot-server 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8b273bf7f49d2acf1743f6ef74ac8e4ca3fc336d
-  data.tar.gz: a4b089d850c7a0cceef7fe9d1643ce4843831b5d
+  metadata.gz: 143cba07b6d366616e823e2f9a502d1d24a4af8d
+  data.tar.gz: b739efffeddf7b60a7e23dc797073f3629285b8f
 SHA512:
-  metadata.gz: 324c943e0ee722c366a08f5fb14e168b3f4145baf951c127bb9f82a5797236410552edbb6bb342da66b2abb41d79692066cab53ae86c4db5cb1335bbc1cfc06f
-  data.tar.gz: 1bfb87e6b026251971e0dd9a35b2601c37845c075910df809112a0c443bdeeafcb4be4cb4c9d5bc0f83daaeafe9defbeef8f6e89e9eea088d3a88396b1be5b36
+  metadata.gz: dfdf002fd3b658f13e6feb5486586e3937c409bc6fad2e45de4b871b7dbf7d0806ed5ac6383b4afb1d88b374bfda9023a0694718aebb6f4941edd375bd777829
+  data.tar.gz: 5bc62c5f100ecc33f77ad809f8ca5952be5e9373ff710c834865f84048bcc2dd72663a9ffe4b0529a7a06e6235c36887b36013542d6d9829d96fc9b73cb78c9d

data/.gitignore

@@ -7,3 +7,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+test_server

data/CHANGELOG.md

@@ -1,7 +1,26 @@
-## 0.3.0
+## 0.4.0
+
+### Added
+- Allow bots to send a 'typing' message
+- Messages will be sent via the Real-Team API if possible (not all message parameters are acceptable there)
+- Subsequent bot callbacks won't fire if an earlier one returns `false`
+- `SlackBotServer::Bot` now exposes `bot_user_name`, `bot_user_id`, `team_name`, and `team_id` methods
+- The logger can now be set via `SlackBotServer.logger=`
+- Access the underlying Slack client via the `SlackBotServer::Bot#client` method
+
+### Changes
+- Swapped internal API library from `slack-api` to `slack-ruby-client`
+- Improve internal bot logging API
+- Ensure rtm data is reloaded when reconnecting
+- Add missing/implicit requires to server.rb and bot.rb
+- Only listen for instructions on the queue if its non-nil
+- Fix bug where malformed bot key could crash when processing instructions
+- Allow `SlackBotServer::RedisQueue.new` to take a custom redis key; note that this has changed the argument format of the initialiser
 
-Changes:
 
-  - The `SlackBotServer::Server#on_new_proc` has been renamed to `Server#on_add`
-  - The `add` and `add_bot` methods on `SlackBotServer::Server` and `SlackBotServer::RemoteControl` control have been merged as `add_bot`
-  - Multiple arguments may be passed via the `add_bot` method to the block given to `SlackBotServer::on_add`
+## 0.3.0
+
+### Changes
+- The `SlackBotServer::Server#on_new_proc` has been renamed to `Server#on_add`
+- The `add` and `add_bot` methods on `SlackBotServer::Server` and `SlackBotServer::RemoteControl` control have been merged as `add_bot`
+- Multiple arguments may be passed via the `add_bot` method to the block given to `SlackBotServer::on_add`

data/README.md

@@ -1,6 +1,6 @@
 # SlackBotServer
 
-[![Build Status](https://travis-ci.org/exciting-io/slack-bot-server.svg)](https://travis-ci.org/exciting-io/slack-bot-server)
+[![Build Status](https://travis-ci.org/exciting-io/slack-bot-server.svg)](https://travis-ci.org/exciting-io/slack-bot-server) [![Documentation](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/github/exciting-io/slack-bot-server)
 
 If you're building an integration just for yourself, running a single bot isn't too hard and there are plenty of examples available. However, if you're building an integration for your *product* to connect with multiple teams, running multiple instances of that bot is a bit trickier.
 
@@ -55,34 +55,7 @@ server.start
 
 Running this script will start a server and keep it running; you may wish to use a tool like [Foreman](http://ddollar.github.io/foreman/) to actually start it and manage it in production.
 
-### Writing a bot
-
-The provided example `SimpleBot` illustrates the main ways to build a bot:
-
-```ruby
-require 'slack_bot_server/bot'
-
-class SlackBotServer::SimpleBot < SlackBotServer::Bot
-  # Set the username displayed in Slack
-  username 'SimpleBot'
-
-  # Respond to mentions in the connected chat room (defaults to #general).
-  # As well as the normal data provided by Slack's API, we add the `message`,
-  # which is the `text` parameter with the username stripped out. For example,
-  # When a user sends 'simple_bot: how are you?', the `message` data contains
-  # only 'how are you'.
-  on_mention do |data|
-    reply text: "You said '#{data['message']}', and I'm frankly fascinated."
-  end
-
-  # Respond to messages sent via IM communication directly with the bot.
-  on_im do
-    reply text: "Hmm, OK, let me get back to you about that."
-  end
-end
-```
-
-### Advanced example
+### Advanced server example
 
 This is a more advanced example of a server script, based on the that used by [Harmonia](https://harmonia.io), the product from which this was extracted.
 
@@ -96,7 +69,7 @@ require 'harmonia/slack_bot'
 # Use a Redis-based queue to add/remove bots and to trigger
 # bot messages to be sent. In this case we connect to the same
 # redis instance as Resque, just for convenience.
-queue = SlackBotServer::RedisQueue.new(Resque.redis)
+queue = SlackBotServer::RedisQueue.new(redis: Resque.redis)
 
 server = SlackBotServer::Server.new(queue: queue)
 
@@ -130,16 +103,65 @@ end
 server.start
 ```
 
+### Writing a bot
+
+The provided example `SimpleBot` illustrates the main ways to build a bot:
+
+```ruby
+require 'slack_bot_server/bot'
+
+class SlackBotServer::SimpleBot < SlackBotServer::Bot
+  # Set the friendly username displayed in Slack
+  username 'SimpleBot'
+  # Set the image to use as an avatar icon in Slack
+  icon_url 'http://my.server.example.com/assets/icon.png'
+
+  # Respond to mentions in the connected chat room (defaults to #general).
+  # As well as the normal data provided by Slack's API, we add the `message`,
+  # which is the `text` parameter with the username stripped out. For example,
+  # When a user sends 'simple_bot: how are you?', the `message` data contains
+  # only 'how are you'.
+  on_mention do |data|
+    if data['message'] == 'who are you'
+      reply text: "I am #{user} (user id: #{user_id}, connected to team #{team} with team id #{team_id}"
+    else
+      reply text: "You said '#{data['message']}', and I'm frankly fascinated."
+    end
+  end
+
+  # Respond to messages sent via IM communication directly with the bot.
+  on_im do
+    reply text: "Hmm, OK, let me get back to you about that."
+  end
+end
+```
+
+As well as the special `on_mention` and `on_im` blocks, there are a number
+of other hooks that you can use when writing a bot:
+
+* `on :message` -- will fire for every message that's received from Slack in
+  the rooms that this bot is a member of
+* `on :start` -- will fire when the bot establishes a connection to Slack
+  (note that periodic disconnections will occur, so this hook is best used
+  to gather data about the current state of Slack. You should not assume
+  this is the first time the bot has ever connected)
+* `on :finish` -- will fire when the bot is disconnected from Slack. This
+  may be because a disconnection happened, or might be because the bot was
+  removed from the server via the `remove_bot` command. You can check if
+  the bot was accidentally/intermittently disconnected via the `running?`
+  method, which will return true unless the bot was explicitly stopped.
+
+
 ### Managing bots
 
-When someone in your application wspants to connect their account with Slack, they'll need to provide a bot API token, which your application should store.
+When someone in your application wants to connect their account with Slack, they'll need to provide a bot API token, which your application should store.
 
 In order to actually create and connect their bot, you can use the remote
 control to add the token to the server.
 
 ```ruby
 # Somewhere within your application
-queue = SlackBotServer::RedisQueue.new(Redis.new)
+queue = SlackBotServer::RedisQueue.new(redis: Redis.new)
 slack_remote = SlackBotServer::RemoteControl.new(queue: queue)
 slack_remote.add_bot('user-accounts-slack-api-token')
 ```
@@ -172,7 +194,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/exciting-io/slack_bot_server.
+Bug reports and pull requests are welcome on GitHub at https://github.com/exciting-io/slack-bot-server.
 
 
 ## License

data/lib/slack_bot_server.rb

@@ -2,10 +2,21 @@ require 'slack_bot_server/version'
 require 'slack_bot_server/server'
 require 'logger'
 
+# A framework for running and controlling multiple bots. This
+# is designed to make it easier for developers to provide Slack
+# integration for their applications, instead of having individual
+# users run their own bot instances.
 module SlackBotServer
+  # A Logger instance, defaulting to +INFO+ level
   def self.logger
     @logger ||= Logger.new(STDOUT)
   end
+
+  # Assign the logger to be used by SlackBotServer
+  # @param logger [Logger]
+  def self.logger=(logger)
+    @logger = logger
+  end
 end
 
 SlackBotServer.logger.level = Logger::INFO

data/lib/slack_bot_server/bot.rb

@@ -1,87 +1,215 @@
 require 'slack'
-require 'slack/client'
-
+require 'slack-ruby-client'
+
+# A superclass for integration bot implementations.
+#
+# A simple example:
+#
+#   class MyBot < SlackBotServer::Bot
+#     # Set the friendly username displayed in Slack
+#     username 'My Bot'
+#     # Set the image to use as an avatar icon in Slack
+#     icon_url 'http://my.server.example.com/assets/icon.png'
+#
+#     # Respond to mentions in the connected chat room (defaults to #general).
+#     # As well as the normal data provided by Slack's API, we add the `message`,
+#     # which is the `text` parameter with the username stripped out. For example,
+#     # When a user sends 'simple_bot: how are you?', the `message` data contains
+#     # only 'how are you'.
+#     on_mention do |data|
+#       if data['message'] == 'who are you'
+#         reply text: "I am #{user} (user id: #{user_id}, connected to team #{team} with team id #{team_id}"
+#       else
+#         reply text: "You said '#{data['message']}', and I'm frankly fascinated."
+#       end
+#     end
+#
+#     # Respond to messages sent via IM communication directly with the bot.
+#     on_im do
+#       reply text: "Hmm, OK, let me get back to you about that."
+#     end
+#   end
+#
 class SlackBotServer::Bot
+
+  # The user ID of the special slack user +SlackBot+
   SLACKBOT_USER_ID = 'USLACKBOT'
 
-  attr_reader :key
+  attr_reader :key, :token, :client
 
+  # Raised if Slack rejected the token during authentication.
   class InvalidToken < RuntimeError; end
 
+  # Create a new bot.
+  # This is normally called from within the block passed to
+  # {SlackBotServer::Server#on_add}, which should return a new
+  # bot instance.
+  # @param token [String] the Slack bot token to use for authentication
+  # @param key [String] a key used to target messages to this bot from
+  #    your application when using {RemoteControl}. If not provided,
+  #    this defaults to the token.
   def initialize(token:, key: nil)
     @token = token
     @key = key || @token
-    @api = ::Slack::Client.new(token: @token)
-    @im_channel_ids = []
-    @channel_ids = []
+    @client = ::Slack::RealTime::Client.new(token: @token)
+    @im_channels = []
+    @channels = []
     @connected = false
     @running = false
 
-    raise InvalidToken unless rtm_start_data['ok']
+    raise InvalidToken unless @client.web_client.auth_test['ok']
+  end
+
+  # Returns the username (for @ replying) of the bot user we are connected as,
+  # e.g. +'simple_bot'+
+  def bot_user_name
+    @client.self['name']
+  end
+
+  # Returns the ID of the bot user we are connected as, e.g. +'U123456'+
+  def bot_user_id
+    @client.self['id']
+  end
+
+  # Returns the name of the team we are connected to, e.g. +'My Team'+
+  def team_name
+    @client.team['name']
+  end
+
+  # Returns the ID of the team we are connected to, e.g. +'T234567'+
+  def team_id
+    @client.team['id']
   end
 
+  # Send a message to Slack
+  # @param options [Hash] a hash containing any of the following:
+  #    channel:: the name ('#general'), or the ID of the channel to send to
+  #    text:: the actual text of the message
+  #    username:: the name the message should appear from; defaults to the
+  #               value given to `username` in the Bot class definition
+  #    icon_url:: the image url to use as the avatar for this message;
+  #               defaults to the value given to `icon_url` in the Bot
+  #               class definition
   def say(options)
-    @api.chat_postMessage(default_message_options.merge(options))
+    message = symbolize_keys(default_message_options.merge(options))
+
+    if rtm_incompatible_message?(message)
+      debug "Sending via Web API", message
+      @client.web_client.chat_postMessage(message)
+    else
+      debug "Sending via RTM API", message
+      @client.message(message)
+    end
   end
 
+  # Sends a message to every channel this bot is a member of
+  # @param options [Hash] As {#say}, although the +:channel+ option is
+  #   redundant
   def broadcast(options)
-    @channel_ids.each do |channel|
-      say(options.merge(channel: channel))
+    @channels.each do |channel|
+      say(options.merge(channel: channel['id']))
     end
   end
 
+  # Sends a reply to the same channel as the last message that was
+  # received by this bot.
+  # @param options [Hash] As {#say}, although the +:channel+ option is
+  #    redundant
   def reply(options)
     channel = @last_received_data['channel']
     say(options.merge(channel: channel))
   end
 
+  # Sends a message via IM to a user
+  # @param user_id [String] the Slack user ID of the person to receive this message
+  # @param options [Hash] As {#say}, although the +:channel+ option is
+  #    redundant
   def say_to(user_id, options)
-    result = @api.im_open(user: user_id)
+    result = @client.web_client.im_open(user: user_id)
     channel = result['channel']['id']
     say(options.merge(channel: channel))
   end
 
+  # Sends a typing notification
+  # @param options [Hash] can contain +:channel+, which should be an ID; if no options
+  #    are provided, the channel from the most recently recieved message is used
+  def typing(options={})
+    last_received_channel = @last_received_data ? @last_received_data['channel'] : nil
+    default_options = {channel: last_received_channel}
+    @client.typing(default_options.merge(options))
+  end
+
+  # Call a method directly on the Slack web API (via Slack::Web::Client).
+  # Useful for debugging only.
   def call(method, args)
     args.symbolize_keys!
-    @api.send(method, args)
+    @client.web_client.send(method, args)
   end
 
+  # Starts the bot running.
+  # You should not call this method; instead, the server will call it
+  # when it is ready for the bot to connect
+  # @see Server#start
   def start
     @running = true
-    @ws = Faye::WebSocket::Client.new(websocket_url, nil, ping: 60)
 
-    @ws.on :open do |event|
+    @client.on :open do |event|
       @connected = true
       log "connected to '#{team_name}'"
       run_callbacks(:start)
     end
 
-    @ws.on :message do |event|
+    @client.on :message do |data|
       begin
-        debug event.data
-        handle_message(event)
+        debug message: data
+        handle_message(data)
       rescue => e
         log error: e
         log backtrace: e.backtrace
       end
     end
 
-    @ws.on :close do |event|
+    @client.on :im_created do |data|
+      log "Adding new IM channel", data['channel']
+      @im_channels << data['channel']
+    end
+
+    @client.on :channel_joined do |data|
+      log "Adding new channel", data['channel']
+      @channels << data['channel']
+    end
+
+    @client.on :channel_left do |data|
+      channel_id = data['channel']
+      log "Removing channel: #{channel_id}"
+      @channels.delete_if { |c| c['id'] == channel_id }
+    end
+
+    @client.on :close do |event|
       log "disconnected"
       @connected = false
-      if @running
-        start
-      end
+      run_callbacks(:finish)
     end
+
+    @client.start_async
   end
 
+  # Stops the bot from running. You should not call this method; instead
+  # send the server a +remote_bot+ message
+  # @see Server#remove_bot
   def stop
     log "closing connection"
     @running = false
-    @ws.close
+    @client.stop!
     log "closed"
   end
 
+  # Returns +true+ if this bot is (or should be) running
+  def running?
+    @running
+  end
+
+  # Returns +true+ if this bot is currently connected to Slack
   def connected?
     @connected
   end
@@ -89,44 +217,117 @@ class SlackBotServer::Bot
   class << self
     attr_reader :mention_keywords
 
+    # Sets the username this bot should use
+    #
+    #   class MyBot < SlackBotServer::Bot
+    #     username 'My Bot'
+    #
+    #     # etc
+    #   end
+    #
+    # will result in the friendly name 'My Bot' appearing beside
+    # the messages in your Slack rooms
     def username(name)
       default_message_options[:username] = name
     end
 
+    # Sets the image to use as an avatar for this bot
+    #
+    #   class MyBot < SlackBotServer::Bot
+    #     icon_url 'http://example.com/bot.png'
+    #
+    #     # etc
+    #   end
     def icon_url(url)
       default_message_options[:icon_url] = url
     end
 
+    # Sets the keywords in messages that will trigger the
+    # +on_mention+ callback
+    #
+    #   class MyBot < SlackBotServer::Bot
+    #     mention_as 'hey', 'bot'
+    #
+    #     # etc
+    #   end
+    #
+    # will mean the +on_mention+ callback fires for messages
+    # like "hey you!" and "bot, what are you thinking".
+    #
+    # Mention keywords are only matched at the start of messages,
+    # so the text "I love you, bot" won't trigger this callback.
+    # To implement general keyword spotting, use a custom
+    # +on :message+ callback.
+    #
+    # If this is not called, the default mention keyword is the
+    # bot username, e.g. +simple_bot+
     def mention_as(*keywords)
       @mention_keywords = keywords
     end
 
+    # Holds default options to send with each message to Slack
     def default_message_options
-      @default_message_options ||= {}
+      @default_message_options ||= {type: 'message'}
     end
 
+    # All callbacks defined on this class
     def callbacks
       @callbacks ||= {}
     end
 
+    # Returns all callbacks (including those in superclasses) for a given
+    # event type
     def callbacks_for(type)
-      matching_callbacks = callbacks[type.to_sym] || []
       if superclass.respond_to?(:callbacks_for)
-        matching_callbacks += superclass.callbacks_for(type)
+        matching_callbacks = superclass.callbacks_for(type)
+      else
+        matching_callbacks = []
       end
-      matching_callbacks.reverse
+      matching_callbacks += callbacks[type.to_sym] if callbacks[type.to_sym]
+      matching_callbacks
     end
 
+    # Register a callback
+    #
+    #   class MyBot < SlackBotServer::Bot
+    #     on :message do
+    #       reply text: 'I heard a message, so now I am responding!'
+    #     end
+    #   end
+    #
+    # Possible callbacks are:
+    #   +:start+ :: fires when the bot establishes a connection to Slack
+    #   +:finish+ :: fires when the bot is disconnected from Slack
+    #   +:message+ :: fires when any message is sent in any channel the bot is
+    #                 connected to
+    #
+    # Multiple blocks for each type can be registered; they will be run
+    # in the order they are defined.
+    #
+    # If any block returns +false+, later blocks will not be fired.
     def on(type, &block)
       callbacks[type.to_sym] ||= []
       callbacks[type.to_sym] << block
     end
 
+    # Define a callback to run when any of the mention keywords are
+    # present in a message.
+    #
+    # Typically this will be for messages in open channels, where as
+    # user directs a message to this bot, e.g. "@simple_bot hello"
+    #
+    # By default, the mention keyword is simply the bot's username
+    # e.g. +simple_bot+
+    #
+    # As well as the raw Slack data about the message, the data +Hash+
+    # yielded to the given block will contain a +'message'+ key,
+    # which holds the text sent with the keyword removed.
     def on_mention(&block)
       on(:message) do |data|
+        debug on_message: data, bot_message: bot_message?(data)
         if !bot_message?(data) &&
            (data['text'] =~ /\A(#{mention_keywords.join('|')})[\s\:](.*)/i ||
-            data['text'] =~ /\A(<@#{user_id}>)[\s\:](.*)/)
+            data['text'] =~ /\A(<@#{bot_user_id}>)[\s\:](.*)/)
           message = $2.strip
           @last_received_data = data.merge('message' => message)
           instance_exec(@last_received_data, &block)
@@ -134,8 +335,11 @@ class SlackBotServer::Bot
       end
     end
 
+    # Define a callback to run when any a user sends a direct message
+    # to this bot
     def on_im(&block)
       on(:message) do |data|
+        debug on_im: data, bot_message: bot_message?(data), is_im_channel: is_im_channel?(data['channel'])
         if is_im_channel?(data['channel']) && !bot_message?(data)
           @last_received_data = data.merge('message' => data['text'])
           instance_exec(@last_received_data, &block)
@@ -148,100 +352,83 @@ class SlackBotServer::Bot
     load_channels
   end
 
-  on :im_created do |data|
-    channel_id = data['channel']['id']
-    log "Adding new IM channel: #{channel_id}"
-    @im_channel_ids << channel_id
-  end
-
-  on :channel_joined do |data|
-    channel_id = data['channel']['id']
-    log "Adding new channel: #{channel_id}"
-    @channel_ids << channel_id
-  end
-
-  on :channel_left do |data|
-    channel_id = data['channel']
-    log "Removing channel: #{channel_id}"
-    @channel_ids.delete(channel_id)
+  on :finish do
+    if @running
+      start
+    end
   end
 
+  # Returns a String representation of this {Bot}
+  # @return String
   def to_s
     "<#{self.class.name} key:#{key}>"
   end
 
   private
 
-  def handle_message(event)
-    data = MultiJson.load(event.data)
-    run_callbacks(data["type"], data) if data["type"]
+  def handle_message(data)
+    run_callbacks(data['type'], data)
   end
 
   def run_callbacks(type, data=nil)
     relevant_callbacks = self.class.callbacks_for(type)
     relevant_callbacks.each do |c|
-      instance_exec(data, &c)
+      response = instance_exec(data, &c)
+      break if response == false
     end
   end
 
-  def log(message)
-    text = message.is_a?(String) ? message : message.inspect
-    text = "[BOT/#{user}] #{text}"
-    SlackBotServer.logger.info(message)
-  end
-
-  def debug(message)
-    text = message.is_a?(String) ? message : message.inspect
-    text = "[BOT/#{user}] #{text}"
-    SlackBotServer.logger.debug(message)
-  end
-
-  def user
-    rtm_start_data['self']['name']
+  def log(*args)
+    SlackBotServer.logger.info(log_string(*args))
   end
 
-  def user_id
-    rtm_start_data['self']['id']
+  def debug(*args)
+    SlackBotServer.logger.debug(log_string(*args))
   end
 
-  def team_name
-    rtm_start_data['team']['name']
+  def log_string(*args)
+    text = if args.length == 1 && args.first.is_a?(String)
+      args.first
+    else
+      args.map { |a| a.is_a?(String) ? a : a.inspect }.join(", ")
+    end
+    "[BOT/#{bot_user_name}] #{text}"
   end
 
   def load_channels
     log "Loading channels"
-    @im_channel_ids = rtm_start_data['ims'].map { |d| d['id'] }
-    log im_channels: @im_channel_ids
-    @channel_ids = rtm_start_data['channels'].select { |d| d['is_member'] == true }.map { |d| d['id'] }
-    log channels: @channel_ids
+    @im_channels = @client.ims
+    log im_channels: @im_channels
+    @channels = @client.channels.select { |d| d['is_member'] == true }
+    log channels: @channels
   end
 
-  def websocket_url
-    rtm_start_data['url']
-  end
-
-  def rtm_start_data
-    @rtm_start_data ||= @api.post('rtm.start')
+  def channel(id)
+    (@channels + @im_channels).find { |c| c['id'] == id }
   end
 
   def is_im_channel?(id)
-    @im_channel_ids.include?(id)
+    channel(id)['is_im'] == true
   end
 
   def bot_message?(data)
     data['subtype'] == 'bot_message' ||
     data['user'] == SLACKBOT_USER_ID ||
-    data['user'] == user_id ||
+    data['user'] == bot_user_id ||
     change_to_previous_bot_message?(data)
   end
 
   def change_to_previous_bot_message?(data)
     data['subtype'] == 'message_changed' &&
-    data['previous_message']['user'] == user_id
+    data['previous_message']['user'] == bot_user_id
   end
 
-  def websocket_url
-    @api.post('rtm.start')['url']
+  def rtm_incompatible_message?(data)
+    data[:attachments].nil? ||
+    data[:username].nil? ||
+    data[:icon_url].nil? ||
+    data[:icon_emoji].nil? ||
+    data[:channel].match(/^#/).nil?
   end
 
   def default_message_options
@@ -249,6 +436,13 @@ class SlackBotServer::Bot
   end
 
   def mention_keywords
-    self.class.mention_keywords || [user]
+    self.class.mention_keywords || [bot_user_name]
+  end
+
+  def symbolize_keys(hash)
+    hash.keys.each do |key|
+      hash[key.to_sym] = hash.delete(key)
+    end
+    hash
   end
 end

data/lib/slack_bot_server/local_queue.rb

@@ -1,12 +1,22 @@
+# A local implementation of a queue.
+#
+# Obviously this can't be used to communicate between
+# multiple processes, let alone multiple machines, but
+# it serves to demonstrate the expected API.
 class SlackBotServer::LocalQueue
+  # Creates a new local in-memory queue
   def initialize
     @queue = Queue.new
   end
 
+  # Push a value onto the back of the queue
   def push(value)
     @queue << value
   end
 
+  # Pop a value from the front of the queue
+  # @return [Object, nil] returns the object from the front of the
+  #    queue, or nil if the queue is empty
   def pop
     value = @queue.pop(true) rescue ThreadError
     value == ThreadError ? nil : value

data/lib/slack_bot_server/redis_queue.rb

@@ -1,8 +1,14 @@
 require 'multi_json'
 
+# An implementation of the quue interface that uses
+# Redis as a data conduit.
 class SlackBotServer::RedisQueue
-  def initialize(redis=nil)
-    @key = 'slack_bot_server:queue'
+  # Creates a new queue
+  # @param redis [Redis] an instance of the ruby +Redis+ client. If
+  #    nil, one will be created using the default hostname and port
+  # @param key [String] the key to store the queue against
+  def initialize(redis: nil, key: 'slack_bot_server:queue')
+    @key = key
     @redis = if redis
       redis
     else
@@ -11,10 +17,15 @@ class SlackBotServer::RedisQueue
     end
   end
 
+  # Push a value onto the back of the queue.
+  # @param value [Object] this will be turned into JSON when stored
   def push(value)
     @redis.rpush @key, MultiJson.dump(value)
   end
 
+  # Pop a value from the front of the queue
+  # @return [Object] the object on the queue, reconstituted from its
+  #    JSON string
   def pop
     json_value = @redis.lpop @key
     if json_value

data/lib/slack_bot_server/remote_control.rb

@@ -3,32 +3,57 @@
 # This should be initialized with a queue that is shared with the
 # targetted server (e.g. the same local queue instance, or a
 # redis queue instance that points at the same redis server).
-
 class SlackBotServer::RemoteControl
+  # Create a new instance of a remote control
+  # @param queue [Object] any Object conforming to the queue API
+  #   (i.e. with #push and #pop methods)
   def initialize(queue:)
     @queue = queue
   end
 
+  # Sends an +add_bot+ command to the {SlackBotServer::Server server}.
+  # See {SlackBotServer::Server#add_bot} for arguments.
   def add_bot(*args)
     @queue.push([:add_bot, *args])
   end
 
+  # Sends a +remove_bot+ command to the server.
+  # @param key [String] the key of the bot to remove.
   def remove_bot(key)
     @queue.push([:remove_bot, key])
   end
 
+  # Sends an +broadcast+ command to the {SlackBotServer::Server server}.
+  # @param key [String] the key of the bot which should send the message
+  # @param message_data [Hash] passed directly to
+  #    {SlackBotServer::Bot#broadcast}; see there for argument details.
   def broadcast(key, message_data)
     @queue.push([:broadcast, key, message_data])
   end
 
+  # Sends an +say+ command to the {SlackBotServer::Server server}.
+  # @param key [String] the key of the bot which should send the message.
+  # @param message_data [Hash] passed directly to
+  #    {SlackBotServer::Bot#say}; see there for argument details.
   def say(key, message_data)
     @queue.push([:say, key, message_data])
   end
 
+  # Sends an +say_to+ command to the {SlackBotServer::Server server}.
+  # @param key [String] the key of the bot which should send the message.
+  # @param user_id [String] the Slack user ID of the person who should
+  #    receive the message.
+  # @param message_data [Hash] passed directly to
+  #    {SlackBotServer::Bot#say_to}; see there for argument details.
   def say_to(key, user_id, message_data)
     @queue.push([:say_to, key, user_id, message_data])
   end
 
+  # Sends a message to be called directly on the slack web API. Generally
+  # for debugging only.
+  # @param key [String] the key of the bot which should send the message.
+  # @param method [String, Symbol] the name of the method to call
+  # @param args [Array] the arguments for the method to call
   def call(key, method, args)
     @queue.push([:call, [key, method, args]])
   end

data/lib/slack_bot_server/server.rb

@@ -1,10 +1,58 @@
 require 'slack_bot_server/bot'
 require 'slack_bot_server/simple_bot'
 require 'slack_bot_server/redis_queue'
+require 'eventmachine'
 
+# Implements a server for running multiple Slack bots. Bots can be
+# dynamically added and removed, and can be interacted with from
+# external services (like your application).
+#
+# To use this, you should create a script to run along side your
+# application. A simple example:
+#
+#     #!/usr/bin/env ruby
+#
+#     require 'slack_bot_server'
+#     require 'slack_bot_server/redis_queue'
+#     require 'slack_bot_server/simple_bot'
+#
+#     # Use a Redis-based queue to add/remove bots and to trigger
+#     # bot messages to be sent
+#     queue = SlackBotServer::RedisQueue.new
+#
+#     # Create a new server using that queue
+#     server = SlackBotServer::Server.new(queue: queue)
+#
+#     # How your application-specific should be created when the server
+#     # is told about a new slack api token to connect with
+#     server.on_add do |token|
+#       # Return a new bot instance to the server. `SimpleBot` is a provided
+#       # example bot with some very simple behaviour.
+#       SlackBotServer::SimpleBot.new(token: token)
+#     end
+#
+#     # Start the server. This method blocks, and will not return until
+#     # the server is killed.
+#     server.start
+#
+# The key features are:
+#
+# * creating a queue as a conduit for commands from your app
+# * creating an instance of {Server} with that queue
+# * defining an #on_add block, which is run whenever you need to
+#   start a new bot. This block contains the custom code relevant to
+#   your particular service, most typically the instantiation of a bot
+#   class that implements the logic you want
+# * calling {Server#start}, to actually run the server and start
+#   listening for commands from the queue and connecting bots to Slack
+#   itself
+#
 class SlackBotServer::Server
   attr_reader :queue
 
+  # Creates a new {Server}
+  # @param queue [Object] anything that implements the queue protocol
+  #   (e.g. #push and #pop)
   def initialize(queue: SlackBotServer::LocalQueue.new)
     @queue = queue
     @bots = {}
@@ -12,41 +60,43 @@ class SlackBotServer::Server
     @running = false
   end
 
-  # Define the block which should be called when the `add_bot` method is
-  # called, or the `add_bot` message is sent via a queue. This block
+  # Define the block which should be called when the #add_bot method is
+  # called, or the +add_bot+ message is sent via a queue. This block
   # should return a bot (which responds to start), in which case it will
   # be added and started. If anything else is returned, it will be ignored.
   def on_add(&block)
     @add_proc = block
   end
 
+  # Starts the server. This method will not return; call it at the
+  # end of your server script. It will start all bots it knows about
+  # (i.e. bots added via #add_bot before the server was started),
+  # and then listen for new instructions.
+  # @see Bot#start
   def start
     EM.run do
       @running = true
       @bots.each { |key, bot| bot.start }
-      add_timers
-    end
-  end
-
-  def add_timers
-    EM.add_periodic_timer(1) do
-      begin
-        next_message = queue.pop
-        process_instruction(next_message) if next_message
-      rescue => e
-        log_error(e)
-      end
+      listen_for_instructions if queue
     end
   end
 
+  # Starts the server in the background, via a Thread
   def start_in_background
     Thread.start { start }
   end
 
+  # Find a bot added to this server. Returns nil if no bot was found
+  # @param key [String] the key of the bot we're looking for
+  # @return Bot
   def bot(key)
     @bots[key.to_sym]
   end
 
+  # Adds a bot to this server
+  # Calls the block given to {#on_add} with the arguments given. The block
+  # should yield a bot, typically a subclass of {Bot}.
+  # @see #on_add
   def add_bot(*args)
     bot = @add_proc.call(*args)
     if bot.respond_to?(:start)
@@ -58,6 +108,9 @@ class SlackBotServer::Server
     log_error(e)
   end
 
+  # Stops and removes a bot from the server
+  # @param key [String] the key of the bot to remove
+  # @see SlackBotServer::Bot#stop
   def remove_bot(key)
     if (bot = bot(key))
       bot.stop
@@ -69,36 +122,45 @@ class SlackBotServer::Server
 
   private
 
+  def listen_for_instructions
+    EM.add_periodic_timer(1) do
+      begin
+        next_message = queue.pop
+        process_instruction(next_message) if next_message
+      rescue => e
+        log_error(e)
+      end
+    end
+  end
+
   def process_instruction(instruction)
     type, *args = instruction
-    case type.to_sym
-    when :add_bot
-      log "adding bot: #{args.inspect}"
-      add_bot(*args)
-    when :remove_bot
-      key = args.first
-      remove_bot(key)
-    when :broadcast
-      key, message_data = args
-      log "[#{key}] broadcast: #{message_data}"
-      bot = bot(key)
-      bot.broadcast(message_data)
-    when :say
-      key, message_data = args
-      log "[#{key}] say: #{message_data}"
-      bot = bot(key)
-      bot.say(message_data)
-    when :say_to
-      key, user_id, message_data = args
-      log "[#{key}] say_to: (#{user_id}) #{message_data}"
-      bot = bot(key)
-      bot.say_to(user_id, message_data)
-    when :call
-      key, method, method_args = args
-      bot = bot(key)
-      bot.call(method, method_args)
+    bot_key = args.shift
+    if type == :add_bot
+      log "adding bot: #{bot_key} #{args.inspect}"
+      add_bot(bot_key, *args)
     else
-      log unknown_command: instruction
+      with_bot(bot_key) do |bot|
+        case type.to_sym
+        when :remove_bot
+          remove_bot(bot_key)
+        when :broadcast
+          log "[#{bot_key}] broadcast: #{args}"
+          bot.broadcast(*args)
+        when :say
+          log "[#{bot_key}] say: #{args}"
+          bot.say(*args)
+        when :say_to
+          user_id, message_data = args
+          log "[#{bot_key}] say_to: (#{user_id}) #{message_data}"
+          bot.say_to(user_id, message_data)
+        when :call
+          method, method_args = args
+          bot.call(method, method_args)
+        else
+          log unknown_command: instruction
+        end
+      end
     end
   end
 
@@ -111,4 +173,12 @@ class SlackBotServer::Server
     SlackBotServer.logger.warn("Error in server: #{e} - #{e.message}")
     SlackBotServer.logger.warn(e.backtrace.join("\n"))
   end
+
+  def with_bot(key)
+    if bot = bot(key)
+      yield bot
+    else
+      log("Unknown bot: #{key}")
+    end
+  end
 end

data/lib/slack_bot_server/simple_bot.rb

@@ -1,5 +1,6 @@
 require 'slack_bot_server/bot'
 
+# A simple demonstration of a bot
 class SlackBotServer::SimpleBot < SlackBotServer::Bot
   # Set the username displayed in Slack
   username 'SimpleBot'
@@ -10,7 +11,11 @@ class SlackBotServer::SimpleBot < SlackBotServer::Bot
   # When a user sends 'simple_bot: how are you?', the `message` data contains
   # only 'how are you'.
   on_mention do |data|
-    reply text: "You said '#{data['message']}', and I'm frankly fascinated."
+    if data['message'] == 'who are you'
+      reply text: "I am #{user} (id: #{user_id}), connected to team #{team} (id #{team_id})"
+    else
+      reply text: "You said '#{data['message']}', and I'm frankly fascinated."
+    end
   end
 
   # Respond to messages sent via IM communication directly with the bot.

data/lib/slack_bot_server/version.rb

@@ -1,3 +1,4 @@
 module SlackBotServer
-  VERSION = "0.3.0"
+  # The current version of the +SlackBotServer+ framework
+  VERSION = "0.4.0"
 end

data/slack_bot_server.gemspec

@@ -19,7 +19,8 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "slack-api", "~> 1.1"
+  spec.add_dependency "slack-ruby-client", "~> 0.5"
+  spec.add_dependency "faye-websocket", "~> 0.10"
   spec.add_dependency "multi_json"
 
   spec.add_development_dependency "bundler", "~> 1.10"
@@ -27,4 +28,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "redis"
   spec.add_development_dependency "rspec"
   spec.add_development_dependency "rspec-eventmachine"
+  spec.add_development_dependency "yard"
 end

metadata

@@ -1,29 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: slack-bot-server
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - James Adam
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-01-10 00:00:00.000000000 Z
+date: 2016-01-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: slack-api
+  name: slack-ruby-client
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: '0.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: faye-websocket
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
 - !ruby/object:Gem::Dependency
   name: multi_json
   requirement: !ruby/object:Gem::Requirement
@@ -108,6 +122,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: This software lets you write and host multiple slack bots, potentially
   for multiple different teams or even services.
 email:
@@ -159,3 +187,4 @@ signing_key:
 specification_version: 4
 summary: A server for hosting slack bots.
 test_files: []
+has_rdoc: