slack-ruby-bot-boilerplate 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c789624ba72b2006ff5c87bc4e19521adede2e9aa144b261c1db2fb818329a56
+  data.tar.gz: aff4faf0c5de0ce2b06c615023b67c26b1bd4b016a614f176c4bb49c297babe0
+SHA512:
+  metadata.gz: 16747df3e9ce75eb19a326ca6d57f00fa6953561964306af2c1b29e785326e2be095534dd6aadaf402eabb79b8db587b1931aee4ba8603c5c3f9fae25107791b
+  data.tar.gz: d9318358837b69624337c6b5ef81d5f7d3f4804f3c7d397d44943f265319559c7ad41444e951faf7ce7793fc54cc4264f5dcc23ac2861e865d48ca092aad015f

data/.gitignore

@@ -0,0 +1,5 @@
+.env
+pkg
+Gemfile.lock
+.bundle
+.idea/

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,16 @@
+AllCops:
+  Exclude:
+    - vendor/**/*
+    - examples/**/vendor/**/*
+    - bin/**/*
+
+Metrics:
+  Enabled: false
+
+Metrics/LineLength:
+  Max: 512
+
+Style/Documentation:
+  Enabled: false
+
+inherit_from: .rubocop_todo.yml

data/.rubocop_todo.yml

@@ -0,0 +1,77 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2018-08-27 14:16:34 +0200 using RuboCop version 0.58.2.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 2
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: auto_detection, squiggly, active_support, powerpack, unindent
+Layout/IndentHeredoc:
+  Exclude:
+    - 'lib/slack-ruby-bot/commands/help.rb'
+    - 'spec/slack-ruby-bot/commands/help_spec.rb'
+
+# Offense count: 1
+Lint/DuplicateMethods:
+  Exclude:
+    - 'lib/slack-ruby-bot/hooks/set.rb'
+
+# Offense count: 2
+Lint/HandleExceptions:
+  Exclude:
+    - 'lib/initializers/giphy.rb'
+    - 'lib/initializers/giphy_client.rb'
+
+# Offense count: 1
+# Cop supports --auto-correct.
+Lint/UnneededCopEnableDirective:
+  Exclude:
+    - 'Gemfile'
+
+# Offense count: 2
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: snake_case, normalcase, non_integer
+Naming/VariableNumber:
+  Exclude:
+    - 'spec/slack-ruby-bot/hooks/set_spec.rb'
+
+# Offense count: 1
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: inline, group
+Style/AccessModifierDeclarations:
+  Exclude:
+    - 'lib/slack-ruby-bot/hooks/hook_support.rb'
+
+# Offense count: 1
+Style/DoubleNegation:
+  Exclude:
+    - 'lib/slack-ruby-bot/commands/base.rb'
+
+# Offense count: 5
+# Cop supports --auto-correct.
+Style/ExpandPathArguments:
+  Exclude:
+    - 'lib/config/application.rb'
+    - 'lib/config/environment.rb'
+    - 'lib/slack-ruby-bot.rb'
+    - 'slack-ruby-bot.gemspec'
+
+# Offense count: 2
+# Cop supports --auto-correct.
+Style/IfUnlessModifier:
+  Exclude:
+    - 'lib/slack-ruby-bot/commands/support/match.rb'
+    - 'lib/slack-ruby-bot/mvc/controller/base.rb'
+
+# Offense count: 2
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: module_function, extend_self
+Style/ModuleFunction:
+  Exclude:
+    - 'lib/initializers/giphy_client.rb'
+    - 'lib/slack-ruby-bot/config.rb'

data/.travis.yml

@@ -0,0 +1,28 @@
+language: ruby
+
+cache: bundler
+
+matrix:
+  include:
+    - rvm: 2.3.0
+      script:
+        - bundle exec danger
+    - rvm: 2.3.0
+      env: CONCURRENCY=celluloid-io
+    - rvm: 2.3.0
+      env: CONCURRENCY=faye-websocket
+    - rvm: 2.3.0
+      env: CONCURRENCY=celluloid-io WITH_GIPHY=true
+    - rvm: 2.3.0
+      env: CONCURRENCY=faye-websocket WITH_GIPHY=true
+    - rvm: 2.3.0
+      env: CONCURRENCY=celluloid-io WITH_GIPHY_CLIENT=true
+    - rvm: 2.3.0
+      env: CONCURRENCY=faye-websocket WITH_GIPHY_CLIENT=true
+    - rvm: 2.5
+      env: CONCURRENCY=async-websocket WITH_GIPHY_CLIENT=true
+    - rvm: ruby-head
+    - rvm: jruby-head
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: jruby-head

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+### 0.1.0
+
+* Refactor fork

data/CONTRIBUTING.md

@@ -0,0 +1,139 @@
+# Contributing to SlackRubyBot
+
+This project is work of [many contributors](https://github.com/slack-ruby/slack-ruby-bot/graphs/contributors).
+
+You're encouraged to submit [pull requests](https://github.com/slack-ruby/slack-ruby-bot/pulls), [propose features and discuss issues](https://github.com/slack-ruby/slack-ruby-bot/issues).
+
+In the examples below, substitute your Github username for `contributor` in URLs.
+
+## Fork the Project
+
+Fork the [project on Github](https://github.com/slack-ruby/slack-ruby-bot) and check out your copy.
+
+```
+git clone https://github.com/contributor/slack-ruby-bot.git
+cd slack-ruby-bot
+git remote add upstream https://github.com/slack-ruby/slack-ruby-bot.git
+```
+
+## Bundle Install and Test
+
+Ensure that you can build the project and run tests.
+
+```
+bundle install
+bundle exec rake
+```
+
+## Run SlackRubyBot in Development
+
+Create a private slack group for yourself.
+
+Create a new Bot Integration under [services/new/bot](http://slack.com/services/new/bot).
+
+![](screenshots/register-bot.png)
+
+On the next screen, note the API token.
+
+Run `SLACK_API_TOKEN=<your API token> foreman start`.
+
+You can also create a `.env` file with `SLACK_API_TOKEN=<your API token>` and just run `foreman start`.
+
+## Create a Topic Branch
+
+Make sure your fork is up-to-date and create a topic branch for your feature or bug fix.
+
+```
+git checkout master
+git pull upstream master
+git checkout -b my-feature-branch
+```
+
+## Write Tests
+
+Try to write a test that reproduces the problem you're trying to fix or describes a feature that you want to build.
+Add to [spec](spec).
+
+We definitely appreciate pull requests that highlight or reproduce a problem, even without a fix.
+
+## Write Code
+
+Implement your feature or bug fix.
+
+Ruby style is enforced with [Rubocop](https://github.com/bbatsov/rubocop).
+Run `bundle exec rubocop` and fix any style issues highlighted.
+
+Make sure that `bundle exec rake` completes without errors.
+
+## Write Documentation
+
+Document any external behavior in the [README](README.md).
+
+## Update Changelog
+
+Add a line to [CHANGELOG](CHANGELOG.md) under *Next Release*.
+Make it look like every other line, including your name and link to your Github account.
+
+## Commit Changes
+
+Make sure git knows your name and email address:
+
+```
+git config --global user.name "Your Name"
+git config --global user.email "contributor@example.com"
+```
+
+Writing good commit logs is important. A commit log should describe what changed and why.
+
+```
+git add ...
+git commit
+```
+
+## Push
+
+```
+git push origin my-feature-branch
+```
+
+## Make a Pull Request
+
+Go to https://github.com/contributor/slack-ruby-bot and select your feature branch.
+Click the 'Pull Request' button and fill out the form. Pull requests are usually reviewed within a few days.
+
+## Rebase
+
+If you've been working on a change for a while, rebase with upstream/master.
+
+```
+git fetch upstream
+git rebase upstream/master
+git push origin my-feature-branch -f
+```
+
+## Update CHANGELOG Again
+
+Update the [CHANGELOG](CHANGELOG.md) with the pull request number. A typical entry looks as follows.
+
+```
+* [#123](https://github.com/slack-ruby/slack-ruby-bot/pull/123): Reticulated splines - [@contributor](https://github.com/contributor).
+```
+
+Amend your previous commit and force push the changes.
+
+```
+git commit --amend
+git push origin my-feature-branch -f
+```
+
+## Check on Your Pull Request
+
+Go back to your pull request after a few minutes and see whether it passed muster with Travis-CI. Everything should look green, otherwise fix issues and amend your commit as described above.
+
+## Be Patient
+
+It's likely that your change will not be merged and that the nitpicky maintainers will ask you to do more, or fix seemingly benign problems. Hang on there!
+
+## Thank You
+
+Please do know that we really appreciate and value your time and work. We love you, really.

data/DEPLOYMENT.md

@@ -0,0 +1,33 @@
+## Installation
+
+Create a new Bot Integration under [services/new/bot](http://slack.com/services/new/bot).
+
+![](screenshots/register-bot.png)
+
+On the next screen, note the API token.
+
+### Environment
+
+#### SLACK_API_TOKEN
+
+Set SLACK_API_TOKEN from the Bot integration settings on Slack.
+
+```
+heroku config:add SLACK_API_TOKEN=...
+```
+
+#### GIPHY_API_KEY
+
+The bot replies with animated GIFs. While it's currently not necessary, you may need to set GIPHY_API_KEY in the future, see [github.com/Giphy/GiphyAPI](https://github.com/Giphy/GiphyAPI) for details.
+
+#### SLACK_RUBY_BOT_ALIASES
+
+Optional names for this bot.
+
+```
+heroku config:add SLACK_RUBY_BOT_ALIASES=":pong: table-tennis ping-pong"
+```
+
+### Heroku Idling
+
+Heroku free tier applications will idle. Either pay 7$ a month for the hobby dyno or use [UptimeRobot](http://uptimerobot.com) or similar to prevent your instance from sleeping or pay for a production dyno.

data/Gemfile

@@ -0,0 +1,9 @@
+source 'http://rubygems.org'
+
+gemspec
+
+gem 'slack-ruby-client', '0.13.2', github: 'slack-ruby/slack-ruby-client'
+
+# group :test do
+#   gem 'slack-ruby-danger', '~> 0.1.0', require: false
+# end

data/LICENSE.md

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2015-2016 Daniel Doubrovkine, Artsy and Contributors
+
+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.

data/README.md

@@ -0,0 +1,688 @@
+Slack-Ruby-Bot-Boilerplate
+==============
+
+A generic Slack bot framework written in Ruby on top of [slack-ruby-client](https://github.com/slack-ruby/slack-ruby-client). This library does all the heavy lifting, such as message parsing, so you can focus on implementing slack bot commands. It also attempts to introduce the bare minimum number of requirements or any sorts of limitations. It's a Slack bot boilerplate.
+
+If you are not familiar with Slack bots or Slack API concepts, you might want to watch [this video](http://code.dblock.org/2016/03/11/your-first-slack-bot-service-video.html).
+
+![](slack.png)
+
+## Useful to Me?
+
+* If you are just trying to send messages to Slack, use [slack-ruby-client](https://github.com/slack-ruby/slack-ruby-client), which this library is built on top of.
+* If you're trying to roll out a full service with Slack button integration, check out [slack-ruby-bot-server](https://github.com/slack-ruby/slack-ruby-bot-server), which uses this library.
+* Otherwise, this piece of the puzzle will help you create a single bot instance for one team.
+
+## Stable Release
+
+You're reading the documentation for the **next** release of slack-ruby-bot.
+Please see the documentation for the [last stable release, v0.11.2](https://github.com/slack-ruby/slack-ruby-bot/tree/v0.11.2) unless you're integrating with HEAD.
+See [CHANGELOG](CHANGELOG.md) for a history of changes and [UPGRADING](UPGRADING.md) for how to upgrade to more recent versions.
+
+## Usage
+
+### A Minimal Bot
+
+#### Gemfile
+
+```ruby
+source 'https://rubygems.org'
+
+gem 'slack-ruby-bot'
+gem 'async-websocket'
+```
+
+#### pongbot.rb
+
+```ruby
+require 'slack-ruby-bot'
+
+class PongBot < SlackRubyBot::Bot
+  command 'ping' do |client, data, match|
+    client.say(text: 'pong', channel: data.channel)
+  end
+end
+
+PongBot.run
+```
+
+After [registering the bot](DEPLOYMENT.md), run with `SLACK_API_TOKEN=... bundle exec ruby pongbot.rb`. Have the bot join a channel and send it a ping.
+
+![](screenshots/demo.gif)
+
+### A Production Bot
+
+A typical production Slack bot is a combination of a vanilla web server and a websocket application that talks to the Slack Real Time Messaging API. See our [Writing a Production Bot](TUTORIAL.md) tutorial for more information.
+
+### More Involved Examples
+
+The following examples of bots based on slack-ruby-bot are listed in growing order of complexity.
+
+* [slack-bot-on-rails](https://github.com/dblock/slack-bot-on-rails): A bot running on Rails and using React to display Slack messages on a website.
+* [slack-mathbot](https://github.com/dblock/slack-mathbot): Slack integration with math.
+* [slack-google-bot](https://github.com/dblock/slack-google-bot): A Slack bot that searches Google, including CSE.
+* [slack-aws](https://github.com/dblock/slack-aws): Slack integration with Amazon Web Services.
+* [slack-deploy-bot](https://github.com/accessd/slack-deploy-bot): A Slack bot that helps you to deploy your apps.
+* [slack-gamebot](https://github.com/dblock/slack-gamebot): A game bot service for ping pong, chess, etc, hosted at [playplay.io](http://playplay.io).
+* [slack-victorbot](https://github.com/uShip/victorbot): A Slack bot to talk to the Victorops service.
+
+### Commands and Operators
+
+Bots are addressed by name, they respond to commands and operators. You can combine multiple commands.
+
+```ruby
+class CallBot < SlackRubyBot::Bot
+  command 'call', '呼び出し' do |client, data, match|
+    client.say(channel: data.channel, text: 'called')
+  end
+end
+```
+
+Command match data includes `match['bot']`, `match['command']` and `match['expression']`. The `bot` match always checks against the `SlackRubyBot::Config.user` and `SlackRubyBot::Config.user_id` values obtained when the bot starts.
+
+The `command` method can take strings, which will have to be escaped with `Regexp.escape`, and regular expressions.
+
+```ruby
+class CallBot < SlackRubyBot::Bot
+  command 'string with spaces', /some\s*regex+\?*/ do |client, data, match|
+    client.say(channel: data.channel, text: match['command'])
+  end
+end
+```
+
+Operators are 1-letter long and are similar to commands. They don't require addressing a bot nor separating an operator from its arguments. The following class responds to `=2+2`.
+
+```ruby
+class MathBot < SlackRubyBot::Bot
+  operator '=' do |client, data, match|
+    # implementation detail
+  end
+end
+```
+
+Operator match data includes `match['operator']` and `match['expression']`. The `bot` match always checks against the `SlackRubyBot::Config.user` setting.
+
+### Threaded Messages
+
+To reply to a message in a thread you must provide a reference to the first message that initiated the thread, which is available as either `data.ts` if no threaded messages have been sent, or `data.thread_ts` if the message being replied to is already in a thread. See [message-threading](https://api.slack.com/docs/message-threading) for more information.
+
+```ruby
+command 'reply in thread' do |client, data, match|
+  client.say(
+    channel: data.channel,
+    text: "let's avoid spamming everyone, I will tell you what you need in this thread",
+    thread_ts: data.thread_ts || data.ts
+  )
+end
+```
+
+_Note that sending a message using only `thread_ts: data.ts` can cause some permanent issues where Slack will keep reporting inaccessible messages as unread. At the time of writing the slack team is still having problems clearing those notifications. As recommended by the slack documentation ..._
+
+> A true parent's thread_ts should be used when replying. Providing a child's message ID will result in a new, detached thread breaking all context and sense.
+
+_... the replies to a thread should always be sent to the message `ts` that started the thread, available as `thread_ts` for subsequent messages. Hence `data.thread_ts || data.ts`._
+
+For additional options, including broadcasting, see [slack-ruby-client#chat_postMessage](https://github.com/slack-ruby/slack-ruby-client/blob/41539c647ac877400f20aa338aa42d2ebfd2866b/lib/slack/web/api/endpoints/chat.rb#L105).
+
+### Bot Aliases
+
+A bot will always respond to its name (eg. `rubybot`) and Slack ID (eg. `@rubybot`), but you can specify multiple aliases via the `SLACK_RUBY_BOT_ALIASES` environment variable or via an explicit configuration.
+
+```
+SLACK_RUBY_BOT_ALIASES=:pp: table-tennis
+```
+
+```ruby
+SlackRubyBot.configure do |config|
+  config.aliases = [':pong:', 'pongbot']
+end
+```
+
+This is particularly fun with emoji.
+
+![](screenshots/aliases.gif)
+
+Bots will also respond to a direct message, with or without the bot name in the message itself.
+
+![](screenshots/dms.gif)
+
+### Generic Routing
+
+Commands and operators are generic versions of bot routes. You can respond to just about anything by defining a custom route.
+
+```ruby
+class Weather < SlackRubyBot::Bot
+  match /^How is the weather in (?<location>\w*)\?$/ do |client, data, match|
+    client.say(channel: data.channel, text: "The weather in #{match[:location]} is nice.")
+  end
+end
+```
+
+![](screenshots/weather.gif)
+
+You can also capture multiple matchers with `scan`.
+
+```ruby
+class Market < SlackRubyBot::Bot
+  scan(/([A-Z]{2,5})/) do |client, data, stocks|
+    # lookup stock market price
+  end
+end
+```
+
+![](screenshots/market.gif)
+
+See [examples/market](examples/market/marketbot.rb) for a working example.
+
+### Matching text in message attachments
+
+You can respond to text in [attachments](https://api.slack.com/docs/message-attachments) with
+`attachment`. It will scan `text`, `pretext` and `title` fields in each attachment until a first
+match is found.
+
+For example you can match [this example attachment](http://goo.gl/K0cLkH)
+by its `title` with the following bot:
+
+```ruby
+class Attachment < SlackRubyBot::Bot
+  attachment 'Slack API Documentation' do |client, data, match|
+    client.say(channel: data.channel, text: "Matched by #{match.attachment_field}.")
+    client.say(channel: data.channel, text: "The attachment's text: #{match.attachment.text}.")
+  end
+end
+```
+
+You can also define which fields in attachment object should be scanned.
+
+Scan only a single field:
+
+```ruby
+class Attachment < SlackRubyBot::Bot
+  attachment 'Slack API Documentation', :title do |client, data, match|
+    # implementation details
+  end
+end
+```
+
+Scan multiple fields:
+
+```ruby
+class Attachment < SlackRubyBot::Bot
+  attachment 'Slack API Documentation', %i[text pretext author_name] do |client, data, match|
+    # implementation details
+  end
+end
+```
+
+### Providing description for your bot and commands
+
+You can specify help information for bot or commands with `help` block, for example:
+
+in case of bot:
+
+```ruby
+class WeatherBot < SlackRubyBot::Bot
+  help do
+    title 'Weather Bot'
+    desc 'This bot tells you the weather.'
+
+    command 'clouds' do
+      desc 'Tells you how many clouds there\'re above you.'
+    end
+
+    command 'What\'s the weather in <city>?' do
+      desc 'Tells you the weather in a <city>.'
+      long_desc "Accurate 10 Day Weather Forecasts for thousands of places around the World.\n" \
+        'Bot provides detailed Weather Forecasts over a 10 day period updated four times a day.'
+    end
+  end
+
+  # commands implementation
+end
+```
+
+![](screenshots/help.png)
+
+in case of your own command:
+
+```ruby
+class Deploy < SlackRubyBot::Commands::Base
+  help do
+    title 'deploy'
+    desc 'deploys your app'
+    long_desc 'command format: *deploy <branch> to <env>* where <env> is production or staging'
+  end
+end
+```
+
+### Customize your command help output
+
+If you've used the `help` block described above to document your
+commands, you can provide your own implementation of outputting help
+for commands like so:
+
+```ruby
+class Market < SlackRubyBot::Bot
+  command 'help' do |client, data, match|
+    user_command = match[:expression]
+    help_attrs = SlackRubyBot::Commands::Support::Help.instance.find_command_help_attrs(user_command)
+    client.say(channel: data.channel, text: "#{help_attrs.command_desc}\n\n#{help_attrs.command_long_desc}"
+  end
+end
+```
+
+### SlackRubyBot::Commands::Base
+
+The `SlackRubyBot::Bot` class is DSL sugar deriving from `SlackRubyBot::Commands::Base`. For more involved bots you can organize the bot implementation into subclasses of `SlackRubyBot::Commands::Base` manually. By default a command class responds, case-insensitively, to its name. A class called `Phone` that inherits from `SlackRubyBot::Commands::Base` responds to `phone` and `Phone` and calls the `call` method when implemented.
+
+```ruby
+class Phone < SlackRubyBot::Commands::Base
+  command 'call'
+
+  def self.call(client, data, match)
+    client.say(channel: data.channel, text: 'called')
+  end
+end
+```
+
+To respond to custom commands and to disable automatic class name matching, use the `command` keyword. The following command responds to `call` and `呼び出し` (call in Japanese).
+
+```ruby
+class Phone < SlackRubyBot::Commands::Base
+  command 'call'
+  command '呼び出し'
+
+  def self.call(client, data, match)
+    client.say(channel: data.channel, text: 'called')
+  end
+end
+```
+
+### Authorization
+
+The framework does not provide any user authentication or command authorization capability out of the box. However, the `SlackRubyBot::Commands::Base` class does check every command invocation for permission prior to executing the command. The default method always returns true.
+
+Therefore, subclasses of `SlackRubyBot::Commands::Base` can override the `permitted?` private method to provide its own authorization logic. This method is intended to be exploited by user code or external gems that want to provide custom authorization logic for command execution.
+
+```ruby
+class AuthorizedBot < SlackRubyBot::Commands::Base
+  command 'phone home' do |client, data, match|
+    client.say(channel: data.channel, text: 'Elliot!')
+  end
+
+  # Only allow user 'Uxyzabc' to run this command
+  def self.permitted?(client, data, match)
+    data && data.user && data.user == 'Uxyzabc'
+  end
+end
+```
+
+### Animated GIFs
+
+The `SlackRubyBot::Client` implementation comes with GIF support. To enable it add `gem GiphyClient` (official Giphy SDK) or `gem giphy` (older SDK, deprecated) to your **Gemfile** and set a Giphy key via `ENV['GIPHY_API_KEY']`. Obtain one from [developers.giphy.com](https://developers.giphy.com).
+
+**Note:** Bots send animated GIFs in default commands and errors.
+
+```ruby
+class Phone < SlackRubyBot::Commands::Base
+  command 'call'
+
+  def self.call(client, data, match)
+    client.say(channel: data.channel, text: 'called', gif: 'phone')
+    # Sends the text 'called' and a random GIF that matches the keyword 'phone'.
+  end
+end
+```
+
+Giphy API key is set automatically via `ENV['GIPHY_API_KEY']`. You can override this manually.
+
+```ruby
+Giphy.configure do |config|
+  config.api_key = 'key'
+end
+```
+
+With `GiphyClient` you can configure the default GIF rating, which supports Y, G, PG, PG-13, and R. The default value is `G`.
+
+```ruby
+Giphy.configure do |config|
+  config.rating = 'Y' # illustrated content only, i.e. cartoons
+end
+```
+
+If you use giphy for something else but don't want your bots to send GIFs you can set `ENV['SLACK_RUBY_BOT_SEND_GIFS']` or `SlackRubyBot::Config.send_gifs` to `false`. The latter takes precedence.
+
+```ruby
+SlackRubyBot.configure do |config|
+  config.send_gifs = false
+end
+```
+
+### Built-In Commands
+
+Slack-ruby-bot comes with several built-in commands. You can re-define built-in commands, normally, as described above.
+
+#### [bot name]
+
+This is also known as the `default` command. Shows bot version and links.
+
+#### [bot name] hi
+
+Politely says 'hi' back.
+
+#### [bot name] help
+
+Get help.
+
+### Hooks
+
+Hooks are event handlers and respond to Slack RTM API [events](https://api.slack.com/events), such as [hello](lib/slack-ruby-bot/hooks/hello.rb) or [message](lib/slack-ruby-bot/hooks/message.rb). You can implement your own in a couple of ways:
+
+#### Implement and register a Hook Handler
+
+A Hook Handler is any object that respond to a `call` message, like a proc, instance of an object, class with a `call` class method, etc.
+
+Hooks can be registered using different methods based on user preference / use case.
+Currently someone can use one of the following methods:
+
+* Pass `hooks` in `SlackRubyBot::Server` initialization.
+* Register `hooks` on `SlackRubyBot::Server` using `on` class method.
+* Register `hooks` on `SlackRubyBot::Server` using `on` instance method.
+
+
+##### Hooks registration on `SlackRubyBot::Server` initialization
+
+```ruby
+SlackRubyBot::Server.new(hook_handlers: {
+  hello: MyBot::Hooks::UserChange.new,
+  user_change: [->(client, data) {  }, ->(client, data) {}]
+})
+```
+
+##### Hooks registration on a `SlackRubyBot::Server` instance
+
+```ruby
+# Register an object that implements `call` method
+class MyBot::Hooks::Hello
+  def call(client, data)
+    puts "Hello"
+  end
+end
+
+server.on(:hello, MyBot::Hooks::Hello.new)
+
+# or register a lambda function to handle the event
+server.on(:hello, ->(client, data) { puts "Hello!" })
+```
+
+For example, the following hook handles [user_change](https://api.slack.com/events/user_change), an event sent when a team member updates their profile or data. This can be useful to update the local user cache when a user is renamed.
+
+```ruby
+module MyBot
+  module Hooks
+    class UserChange
+      def call(client, data)
+        # data['user']['id'] contains the user ID
+        # data['user']['name'] contains the new user name
+        # ...
+      end
+    end
+  end
+end
+```
+
+##### Hooks registration on `SlackRubyBot::Server` class
+
+Example:
+
+```ruby
+module MyBot
+  class MyServer < SlackRubyBot::Server
+    on 'hello' do |client, data|
+      # data['user']['id'] contains the user ID
+      # data['user']['name'] contains the new user name
+    end
+
+    on 'user_change', ->(client, data) {
+      # data['user']['id'] contains the user ID
+      # data['user']['name'] contains the new user name
+    }
+  end
+end
+```
+
+These will get pushed into the hook set on initialization.
+
+Either by configuration, explicit assignment or hook blocks, multiple handlers can exist for the same event type.
+
+
+#### Deprecated hook registration
+
+Registering a hook method using `hooks.add` is considered deprecated and
+will be removed on future versions.
+
+```ruby
+# [DEPRECATED]
+server.hooks.add(:hello, MyBot::Hooks::UserChange.new)
+server.hooks.add(:hello, ->(client, data) { puts "Hello!" })
+
+```
+
+### Message Loop Protection
+
+By default bots do not respond to their own messages. If you wish to change that behavior, set `allow_message_loops` to `true`.
+
+```ruby
+SlackRubyBot.configure do |config|
+  config.allow_message_loops = true
+end
+```
+
+### Logging
+
+By default bots set a logger to `$stdout` with `DEBUG` level. The logger is used in both the RealTime and Web clients.
+
+Silence logger as follows.
+
+```ruby
+SlackRubyBot::Client.logger.level = Logger::WARN
+```
+
+If you wish to customize logger, set `logger` to your logger.
+
+```ruby
+SlackRubyBot.configure do |config|
+  config.logger = Logger.new("slack-ruby-bot.log", "daily")
+end
+```
+
+### Advanced Integration
+
+You may want to integrate a bot or multiple bots into other systems, in which case a globally configured bot may not work for you. You may create instances of [SlackRubyBot::Server](lib/slack-ruby-bot/server.rb) which accepts `token`, `aliases` and `send_gifs`.
+
+```ruby
+EM.run do
+  bot1 = SlackRubyBot::Server.new(token: token1, aliases: ['bot1'])
+  bot1.start_async
+
+  bot2 = SlackRubyBot::Server.new(token: token2, send_gifs: false, aliases: ['bot2'])
+  bot2.start_async
+end
+```
+
+For an example of advanced integration that supports multiple teams, see [slack-gamebot](https://github.com/dblock/slack-gamebot) and [playplay.io](http://playplay.io) that is built on top of it.
+
+### Proxy Configuration
+
+There are [several proxy options](https://github.com/slack-ruby/slack-ruby-client#web-client-options) that can be configured on `Slack::Web::Client`. You can also control what proxy options are used by modifying the `http_proxy` environment variable per [Net::HTTP's documentation](https://docs.ruby-lang.org/en/2.0.0/Net/HTTP.html#class-Net::HTTP-label-Proxies).
+
+Note that Docker on OSX seems to incorrectly set the proxy, [causing `Faraday::ConnectionFailed`](https://github.com/slack-ruby/slack-ruby-bot/issues/155), `ERROR -- : Failed to open TCP connection to : (getaddrinfo: Name or service not known)`. You might need to manually unset `http_proxy` in that case, eg. `http_proxy="" bundle exec ruby ./my_bot.rb`.
+
+### Model-View-Controller Design
+
+The `command` method is essentially a controller method that receives input from the outside and acts upon it. Complex behaviors could lead to a long and difficult-to-understand `command` block. A complex `command` block is a candidate for separation into classes conforming to the Model-View-Controller pattern popularized by Rails.
+
+The library provides three helpful base classes named `SlackRubyBot::MVC::Model::Base`, `SlackRubyBot::MVC::View::Base`, and `SlackRubyBot::MVC::Controller::Base`.
+
+Testing a `command` block is difficult. As separate classes, the Model/View/Controller's behavior can be tested via `rspec` or a similar tool.
+
+#### Controller
+
+The Controller is the focal point of the bot behavior. Typically the code that would go into the `command` block will now go into an instance method in a Controller subclass. The instance method name should match the command name exactly (case sensitive).
+
+As an example, these two classes are functionally equivalent.
+
+Consider the following `Agent` class which is the simplest default approach to take.
+
+```ruby
+class Agent < SlackRubyBot::Bot
+  command 'sayhello', 'alternate way to call hello' do |client, data, match|
+    client.say(channel: data.channel, text: "Received command #{match[:command]} with args #{match[:expression]}")
+  end
+end
+```
+
+Using the MVC functionality, we would create a controller instead to encapsulate this function.
+```ruby
+class MyController < SlackRubyBot::MVC::Controller::Base
+  def sayhello
+    client.say(channel: data.channel, text: "Received command #{match[:command]} with args #{match[:expression]}")
+  end
+  alternate_name :sayhello, :alternate_way_to_call_hello
+end
+MyController.new(MyModel.new, MyView.new)
+```
+Note in the above example that the Controller instance method `sayhello` does not receive any arguments. When the instance method is called, the Controller class sets up some accessor methods to provide the normal `client`, `data`, and `match` objects. These are the same objects passed to the `command` block.
+
+However, the Controller anticipates that the model and view objects should contain business logic that will also operate on the `client`, `data`, and `match` objects. The controller provides access to the model and view via the `model` and `view` accessor methods. The [inventory example](examples/inventory/inventorybot.rb) provides a full example of a Model, View, and Controller working together.
+
+A Controller may need helper methods for certain work. To prevent the helper method from creating a route that the bot will respond to directly, the instance method name should begin with an underscore (e.g. `_my_helper_method`). When building the bot routes, these methods will be skipped.
+
+Calling `alternate_name` after the method definition allows for method aliases similar to the regular `command` structure. When commands can be triggered by multiple text strings it's useful to have that ability map to the controller methods too.
+
+Lastly, the Controller class includes `ActiveSupport::Callbacks` which allows for full flexibility in creating `before`, `after`, and `around` hooks for all methods. Again, see the [inventory example](examples/inventory/inventorybot.rb) for more information.
+
+#### Model
+
+A complex bot may need to read or write data from a database or other network resource. Setting up and tearing down these connections can be costly, so the model can do it once upon instantiation.
+
+The Model also includes `ActiveSupport::Callbacks`.
+
+```ruby
+class MyModel < SlackRubyBot::MVC::Model::Base
+  define_callbacks :sanitize
+  set_callback :sanitize, :around, :sanitize_resource
+  attr_accessor :_resource
+
+  def initialize
+    @db = setup_database_connection
+  end
+
+  def read(resource)
+    self._resource = resource
+    run_callbacks :sanitize do
+      @db.select(:column1 => resource)
+      # ... do some expensive work
+    end
+  end
+
+  private
+
+  def sanitize_resource
+    self._resource.downcase
+    result = yield
+    puts "After read, result is #{result.inspect}"
+  end
+end
+```
+
+Like Controllers, the Model is automatically loaded with the latest version of the `client`, `data`, and `match` objects each time the controller method is called. Therefore the model will always have access to the latest objects when doing its work. It will typically only use the `data` and `match` objects.
+
+Model methods are not matched to routes, so there is no restriction on how to name methods as there is in Controllers.
+
+#### View
+
+A typical bot just writes to a channel or uses the web client to react/unreact to a message. More complex bots will probably require more complex behaviors. These should be stored in a `SlackRubyBot::MVC::View::Base` subclass.
+
+```ruby
+class MyView < SlackRubyBot::MVC::View::Base
+  define_callbacks :logit
+  set_callbacks :logit, :around, :audit_trail
+
+  def initialize
+    @mailer = setup_mailer
+    @ftp = setup_ftp_handler
+  end
+
+  def email_admin(message)
+    run_callbacks :logit do
+      @mailer.send(:administrator, message)
+    end
+  end
+
+  def react_thumbsup
+    client.web_client.reactions_add(
+      name: :thumbs_up,
+      channel: data.channel,
+      timestamp: data.ts,
+      as_user: true)
+  end
+
+  def react_thumbsdown
+    client.web_client.reactions_remove(
+      name: :thumbs_up,
+      channel: data.channel,
+      timestamp: data.ts,
+      as_user: true)
+  end
+
+  private
+
+  def audit_trail
+    Logger.audit("Sending email at [#{Time.now}]")
+    yield
+    Logger.audit("Email sent by [#{Time.now}]")
+  end
+end
+```
+Again, the View will have access to the most up to date `client`, `data`, and `match` objects. It will typically only use the `client` and `data` objects.
+
+View methods are not matched to routes, so there is no restriction on how to name methods as there is in Controllers.
+
+### RSpec Shared Behaviors
+
+Slack-ruby-bot ships with a number of shared RSpec behaviors that can be used in your RSpec tests.
+
+* [behaves like a slack bot](lib/slack-ruby-bot/rspec/support/slack-ruby-bot/it_behaves_like_a_slack_bot.rb): A bot quacks like a Slack Ruby bot.
+* [respond with slack message](lib/slack-ruby-bot/rspec/support/slack-ruby-bot/respond_with_slack_message.rb): The bot responds with a message.
+* [respond with slack messages](lib/slack-ruby-bot/rspec/support/slack-ruby-bot/respond_with_slack_messages.rb): The bot responds with a multiple messages.
+* [respond with error](lib/slack-ruby-bot/rspec/support/slack-ruby-bot/respond_with_error.rb): An exception is raised inside a bot command.
+
+Require `slack-ruby-bot/rspec` in your `spec_helper.rb` along with the following dependencies in Gemfile.
+
+```ruby
+group :development, :test do
+  gem 'rack-test'
+  gem 'rspec'
+  gem 'vcr'
+  gem 'webmock'
+end
+```
+
+### Useful Libraries
+
+* [newrelic-slack-ruby-bot](https://github.com/dblock/newrelic-slack-ruby-bot): NewRelic instrumentation for slack-ruby-bot.
+
+## Contributing
+
+See [CONTRIBUTING](CONTRIBUTING.md).
+
+## Upgrading
+
+See [CHANGELOG](CHANGELOG.md) for a history of changes and [UPGRADING](UPGRADING.md) for how to upgrade to more recent versions.
+
+## Copyright and License
+
+Copyright (c) 2015-2016, [Daniel Doubrovkine](https://twitter.com/dblockdotorg), [Artsy](https://www.artsy.net) and [Contributors](CHANGELOG.md).
+
+This project is licensed under the [MIT License](LICENSE.md).