slack-bot-server 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 61c3888618c930da32157133af1fd57ac3a40123
-  data.tar.gz: 4f7c8adff1540e9162cef41f0ade4a2ee06aeb39
+  metadata.gz: d1a580f416814eef8f1582047b3f748022b2f094
+  data.tar.gz: e307931094203fe4590049d3d4eb966ad4a96fed
 SHA512:
-  metadata.gz: 051cc3a2f27714cf76559aab701dbdb2194eaba113376eb832d886b61116b3c5240c8bcf9beb3cac01c23ee7bc247c61838f234774f8ff9a64ac0c98fe76568f
-  data.tar.gz: 76c4c6ee283a948aa13330b0e237bbbbc1562013b0077903cb0d45fb44d5cb5c3c6219d1188361ef0104adc31a1613dfa9951b570cf2e3e52071fd6840e0e506
+  metadata.gz: 88d60ed5fc1b11d4df51d4ebfe9f92042e660a61bed513130d22a200fb4bee70001655320f5683b0c0418336ec50ede9facfbc36961105bbfa90199b1962a0d2
+  data.tar.gz: 48eae3c8528df390699a124782b558d64d36685d4f83b014b11dc3b4d89857c654c6c27efdfb02ae47e200b112e8c5773af0ed0b1eaebd9c0c4a992f8b8ac721

data/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing
+
+Thanks for helping make this software better! Contributing is super easy, with just a few guidelines.
+
+## Bugs
+
+If you've found a bug in the software, please report it using [GitHub Issues](https://github.com/exciting-io/slack_bot_server/issues). Please include the version (or SHA) of this project that you're using, along with which version of Ruby and any other dependencies that you think might be relevant.
+
+## Features
+
+If you'd got an idea for an improvement or a new feature, that's fantastic! We only ask that you also include specs to cover that behaviour, and that you implement it in a branch to easy merging.
+
+1. Create a new branch for your feature
+2. Implement it, along with new/modified specs
+3. Submit a pull request describing the motivation for your new feature, and how to use it.
+
+Please don't bump the gem version -- we'll take care of that.
+
+Thanks again, and have a great day!

data/README.md

@@ -1,8 +1,10 @@
 # SlackBotServer
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/slack_bot_server`. To experiment with that code, run `bin/console` for an interactive prompt.
+[![Build Status](https://travis-ci.org/exciting-io/slack-bot-server.svg)](https://travis-ci.org/exciting-io/slack-bot-server)
 
-TODO: Delete this and the text above, and describe your gem
+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.
+
+This server is designed to hopefully make it easier to manage running bots for multiple teams at the same time, including managing their connections and adding and removing them dynamically.
 
 ## Installation
 
@@ -22,17 +24,146 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+To use the server in your application, you'll need to create a short script that sets up your integration and then runs the server process. Here's a simple example:
+
+```ruby
+#!/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(Redis.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_new_token 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
+
+# Actually start the server. This line is blocking; code after
+# it won't be executed.
+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
+
+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.
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'slack_bot_server'
+require 'slack_bot_server/redis_queue'
+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)
+
+server = SlackBotServer::Server.new(queue: queue)
+
+server.on_new_token do |token|
+  # Our bots need to know some data about the team they are connecting
+  # to, like specifics of their account and their tasks
+  team_data = Harmonia.find_team_data_by_slack_api_token(token)
+
+  # Our bot instance stores that data in an instance variable internally
+  # and then refers to it when it receives messages
+  Harmonia::SlackBot.new(token: token, data: team_data)
+end
+
+# When the server starts we need to find all the teams which have already
+# set up integrations and ensure their bots are launched immediately
+Harmonia.all_existing_slack_api_tokens.each do |token|
+  server.add_token(token)
+end
+
+# Actually start the server. The pre-loaded bots will connect immediately,
+# and we can add new bots by sending messages using the queue.
+server.start
+```
+
+### 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.
+
+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)
+slack_remote = SlackBotServer::RemoteControl.new(queue: queue)
+slack_remote.add_token('user-accounts-slack-api-token')
+```
+
+This will queue the token to be added by the server, using the `on_new_token` block provided in the server script.
+
+When a bot is created and added within the server, it is stored using a key, which the bot class itself can define, but defaults to the slack api token used to instantiate the bot.
+
+Similarly, if a user disables their Slack integration, we should remove the bot. To remove a bot, call the `remove_bot` method on the remote using the key for the appropriate bot:
+
+```ruby
+slack_remote.remove_bot('bot-key-which-is-normally-the-slack-api-token')
+```
+
+### Getting bots to talk
+
+Up to this point, your bots could only respond to mentions and IM messages, but it's often useful to be able to externally trigger a bot into making an announcement.
+
+We can tell a bot to send a message into its default room fairly simply using the remote:
+
+```ruby
+slack_remote.say('bot-key', text: 'I have an important announcement to make!')
+```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment. Run `bundle exec slack_bot_server` to use the gem in this directory, ignoring other installed copies of this gem.
+After checking out the repo, run `bundle` to install dependencies. Then, run `rake rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment. Run `bundle exec slack_bot_server` to use the gem in this directory, ignoring other installed copies of this gem.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/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/bot.rb

@@ -1,14 +1,13 @@
 require 'slack'
-require 'securerandom'
 
 class SlackBotServer::Bot
   attr_reader :key
 
   class InvalidToken < RuntimeError; end
 
-  def initialize(token:, key: SecureRandom.uuid)
+  def initialize(token:, key: nil)
     @token = token
-    @key = key
+    @key = key || @token
     @api = ::Slack::Client.new(token: @token)
     @im_channel_ids = []
 

data/lib/slack_bot_server/remote_control.rb

@@ -5,7 +5,7 @@
 # redis queue instance that points at the same redis server).
 
 class SlackBotServer::RemoteControl
-  def initialize(queue)
+  def initialize(queue: queue)
     @queue = queue
   end
 
@@ -17,6 +17,10 @@ class SlackBotServer::RemoteControl
     @queue.push([:remove_bot, key])
   end
 
+  def say(key, message_data)
+    @queue.push([:say, key, message_data])
+  end
+
   def call(key, method, args)
     @queue.push([:call, [key, method, args]])
   end

data/lib/slack_bot_server/server.rb

@@ -77,6 +77,10 @@ class SlackBotServer::Server
     when :remove_bot
       key = args.first
       remove_bot(key)
+    when :say
+      key, message_data = args
+      bot = bot(key)
+      bot.say(message_data)
     when :call
       key, method, method_args = args
       bot = bot(key)

data/lib/slack_bot_server/simple_bot.rb

@@ -1,12 +1,19 @@
 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

data/lib/slack_bot_server/version.rb

@@ -1,3 +1,3 @@
 module SlackBotServer
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: slack-bot-server
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - James Adam
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-06-24 00:00:00.000000000 Z
+date: 2015-06-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: slack-api
@@ -105,6 +105,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- CONTRIBUTING.md
 - Gemfile
 - LICENSE.txt
 - README.md