README.md in slack-ruby-bot-server-0.9.0 vs README.md in slack-ruby-bot-server-0.10.0
- old
+ new
@@ -11,11 +11,11 @@
A library that contains a [Grape](http://github.com/ruby-grape/grape) API serving a [Slack Ruby Bot](https://github.com/slack-ruby/slack-ruby-bot) to multiple teams. This gem combines a web server, a RESTful API and multiple instances of [slack-ruby-bot](https://github.com/slack-ruby/slack-ruby-bot). It integrates with the [Slack Platform API](https://medium.com/slack-developer-blog/launch-platform-114754258b91#.od3y71dyo). Your customers can use a Slack button to install the bot.
### Stable Release
-You're reading the documentation for the **stable** release of slack-ruby-bot-server, v0.9.0. See [UPGRADING](UPGRADING.md) when upgrading from an older version.
+You're reading the documentation for the **stable** release of slack-ruby-bot-server, v0.10.0. See [UPGRADING](UPGRADING.md) when upgrading from an older version.
### Try Me
A demo version of the [sample app with mongoid](sample_apps/sample_app_mongoid) is running on Heroku at [slack-ruby-bot-server.herokuapp.com](https://slack-ruby-bot-server.herokuapp.com). Use the _Add to Slack_ button. The bot will join your team as _@slackbotserver_.
@@ -101,19 +101,19 @@
You can introduce custom behavior into the service lifecycle via callbacks. This can be useful when new team has been registered via the API or a team has been deactivated from Slack.
```ruby
instance = SlackRubyBotServer::Service.instance
-instance.on :created do |team, error|
+instance.on :created do |team, error, options|
# a new team has been registered
end
-instance.on :deactivated do |team, error|
+instance.on :deactivated do |team, error, options|
# an existing team has been deactivated in Slack
end
-instance.on :error do |team, error|
+instance.on :error do |team, error, options|
# an error has occurred
end
```
The following callbacks are supported. All callbacks receive a `team`, except `error`, which receives a `StandardError` object.
@@ -130,10 +130,29 @@
| starting | the service is (re)connecting a team to Slack |
| started | the service has (re)connected a team to Slack |
| deactivating | a team is being deactivated |
| deactivated | a team has been deactivated |
+
+The [Add to Slack button](https://api.slack.com/docs/slack-button) also allows for an optional `state` parameter that will be returned on completion of the request. The `creating` and `created` callbacks include an options hash where this value can be accessed (to check for forgery attacks for instance).
+```ruby
+auth = OpenSSL::HMAC.hexdigest("SHA256", "key", "data")
+```
+```html
+<a href="https://slack.com/oauth/authorize?scope=bot&client_id=<%= ENV['SLACK_CLIENT_ID'] %>&state=#{auth)"> ... </a>
+```
+```ruby
+instance = SlackRubyBotServer::Service.instance
+instance.on :creating do |team, error, options|
+ raise "Unauthorized response" unless options[:state] == auth
+end
+```
+
+A number of extensions use service manager callbacks to implement useful functionality.
+
+* [slack-ruby-bot-server-mailchimp](https://github.com/slack-ruby/slack-ruby-bot-server-mailchimp): Subscribes new bot users to a Mailchimp mailing list.
+
#### Server Class
You can override the server class to handle additional events, and configure the service to use it.
```ruby
@@ -150,17 +169,35 @@
SlackRubyBotServer.configure do |config|
config.server_class = MyServer
end
```
+#### Service Class
+
+You can override the service class to handle additional methods.
+
+```ruby
+class MyService < SlackRubyBotServer::Service
+ def url
+ 'https://www.example.com'
+ end
+end
+
+SlackRubyBotServer.configure do |config|
+ config.service_class = MyService
+end
+
+SlackRubyBotServer::Service.instance # MyService
+SlackRubyBotServer::Service.instance.url # https://www.example.com
+```
+
### Access Tokens
-By default the implementation of [Team](lib/slack-ruby-bot-server/models/team) stores a `bot_access_token` that grants a certain amount of privileges to the bot user as described in [Slack OAuth Docs](https://api.slack.com/docs/oauth). You may not want a bot user at all, or may require different auth scopes, such as `users.profile:read` to access user profile information via `Slack::Web::Client#users_profile_get`. To obtain the non-bot access token make the following changes.
+By default the implementation of [Team](lib/slack-ruby-bot-server/models/team) stores a `bot_access_token` as `token` that grants a certain amount of privileges to the bot user as described in [Slack OAuth Docs](https://api.slack.com/docs/oauth) along with `activated_user_access_token` that represents the token of the installing user. You may not want a bot user at all, or may require different auth scopes, such as `users.profile:read` to access user profile information via `Slack::Web::Client#users_profile_get`. To change required scopes make the following changes.
1) Configure your app to require additional scopes in Slack API under _OAuth_, _Permissions_
-2) Add `access_token` and, optionally, `scope` to your `Team` model
-3) Change the _Add to Slack_ buttons to require the additional scope, eg. `https://slack.com/oauth/authorize?scope=bot,users.profile:read&client_id=...`
-4) Store the access token returned from `Slack::Web::Client#oauth_access` and scope when creating a team in your `Teams` API endpoint.
+2) Change the _Add to Slack_ buttons to require the additional scope, eg. `https://slack.com/oauth/authorize?scope=bot,users.profile:read&client_id=...`
+3) The access token with the requested scopes will be stored as `activated_user_access_token`.
You can see a sample implementation in [slack-sup#3a497b](https://github.com/dblock/slack-sup/commit/3a497b436d25d3a7738562655cda64b180ae0096).
### Examples Using Slack Ruby Bot Server