Removed RTM sample apps, updated documentation.

Author: dblock

.travis.yml

@@ -31,4 +31,3 @@ before_install:
 
 script:
   - bundle exec rake
-  - BUNDLE_GEMFILE=Gemfile && cd sample_apps/sample_app_$DATABASE_ADAPTER && bundle && bundle exec rake

DEBUGGING.md

@@ -3,23 +3,3 @@
 ### Locally
 
 You can debug your instance of slack-ruby-bot-server with a built-in `script/console`.
-
-### Silence Mongoid Logger
-
-If Mongoid logging is annoying you.
-
-```ruby
-Mongoid.logger.level = Logger::INFO
-Mongo::Logger.logger.level = Logger::INFO
-```
-
-### Heroku
-
-```
-heroku run script/console --app=...
-
-Running `script/console` attached to terminal... up, run.7593
-
-2.2.1 > Team.count
-=> 3
-```

README.md

@@ -7,10 +7,6 @@ Slack Ruby Bot Server
 
 Build a complete Slack bot service with Slack button integration, in Ruby.
 
-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).
-
-A good [open-source demo](https://github.com/dblock/slack-strava) of a service built on top of this library is [Strava integration with Slack](https://slava.playplay.io).
-
 # Table of Contents
 
 - [What is this?](#what-is-this)
@@ -36,25 +32,19 @@ A good [open-source demo](https://github.com/dblock/slack-strava) of a service b
 
 ### What is this?
 
-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.
+A library that contains a web server and a RESTful [Grape](http://github.com/ruby-grape/grape) API serving a Slack bot to multiple teams. Use in conjunction with [slack-ruby-bot-server-events](https://github.com/slack-ruby/slack-ruby-bot-server-events) to build a complete Slack bot service, or [slack-ruby-bot-server-rtm](https://github.com/slack-ruby/slack-ruby-bot-server-rtm) to build a Class RealTime Slack bot. Your customers can use a Slack button to install the bot.
 
 ### Stable Release
 
 You're reading the documentation for the **next** release of slack-ruby-bot-server. Please see the documentation for the [last stable release, v0.12.3](https://github.com/slack-ruby/slack-ruby-bot-server/blob/v0.12.3/README.md) unless you're integrating with HEAD. 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_.
-
-![](images/slackbutton.gif)
+### Make Your Own
 
-Once a bot is registered, you can invite to a channel with `/invite @slackbotserver` interact with it. DM "hi" to it, or say "@slackbotserver hi".
+We recommend you get started from a [slack-ruby-bot-events-sample](https://github.com/slack-ruby/slack-ruby-bot-server-events-sample) app to bootstrap your project.
 
-![](images/slackbotserver.gif)
+### Storage
 
-### Run Your Own
-
-You can use one of the [sample applications](sample_apps) to bootstrap your project and start adding slack command handlers on top of this code. A database is required to store teams.
+A database is required to store teams.
 
 ### MongoDB
 
@@ -67,8 +57,6 @@ gem 'mongoid-scroll'
 gem 'slack-ruby-bot-server'
 ```
 
-See the [sample app using Mongoid](sample_apps/sample_app_mongoid) for more information.
-
 ### ActiveRecord
 
 Use ActiveRecord with, for example, PostgreSQL via [pg](https://github.com/ged/ruby-pg). Configure the database connection in `postgresql.yml`. Add the `activerecord`, `pg`, `otr-activerecord` and `cursor_pagination` gems to your Gemfile.
@@ -81,11 +69,9 @@ gem 'otr-activerecord'
 gem 'cursor_pagination'
 ```
 
-See the [sample app using ActiveRecord](sample_apps/sample_app_activerecord) for more information.
-
 ### Usage
 
-Start with one of the samples above, which contain a couple of custom commands, necessary dependencies and tests, then [create a new Slack App](https://api.slack.com/applications/new).
+Start with the [slack-ruby-bot-events-sample](https://github.com/slack-ruby/slack-ruby-bot-server-events-sample) sample, which contain a couple of custom commands, necessary dependencies and tests, then [create a new Slack App](https://api.slack.com/applications/new).
 
 ![](images/create-app.png)
 
@@ -97,6 +83,13 @@ Run `bundle install` and `foreman start` to boot the app. Navigate to [localhost
 
 ### OAuth Code Grant
 
+Configure your app's [OAuth scopes](https://api.slack.com/legacy/oauth-scopes) as needed by your application.
+
+```ruby
+SlackRubyBotServer.configure do |config|
+  config.oauth_scope = ['channels:read', 'chat:write:user']
+```
+
 The "Add to Slack" button uses the standard OAuth code grant flow as described in the [Slack docs](https://api.slack.com/docs/oauth#flow).
 
 The button itself contains a link that looks like this:
@@ -105,28 +98,11 @@ The button itself contains a link that looks like this:
 https://slack.com/oauth/authorize?scope=<%= SlackRubyBotServer::Config.oauth_scope_s %>&client_id=<%= ENV['SLACK_CLIENT_ID'] %>
 ```
 
-Once clicked, the user is taken through the authorization process at Slack's site. Upon successful completion, a callback containing a temporary code is sent to the redirect URL you specified. The endpoint at that URL contains code that looks like this:
-
-```ruby
-# Instantiate a web client
-client = Slack::Web::Client.new
-
-# Request a token using the temporary code
-rc = client.oauth_access(
-  client_id: ENV['SLACK_CLIENT_ID'],
-  client_secret: ENV['SLACK_CLIENT_SECRET'],
-  code: params[:code]
-)
-
-# Pluck the token from the response
-token = rc['bot']['bot_access_token']
-```
-
-The token is stored in persistent storage and used each time a Slack client is instantiated for the specific team.
+Once clicked, the user is taken through the authorization process at Slack's site. Upon successful completion, a callback containing a temporary code is sent to the redirect URL you specified. The endpoint at that URL contains code that persists the bot token each time a Slack client is instantiated for the specific team.
 
 ### API
 
-This library implements an app, [SlackRubyBotServer::App](lib/slack-ruby-bot-server/app.rb), a service manager, [SlackRubyBotServer::Service](lib/slack-ruby-bot-server/service.rb) that creates multiple instances of a bot server class, [SlackRubyBotServer::Server](lib/slack-ruby-bot-server/server.rb), one per team. It also provides [default HTML templates and JS scripts](public) for Slack integration.
+This library implements an app, [SlackRubyBotServer::App](lib/slack-ruby-bot-server/app.rb) and a service manager, [SlackRubyBotServer::Service](lib/slack-ruby-bot-server/service.rb). It also provides [default HTML templates and JS scripts](public) for Slack integration.
 
 #### App
 
@@ -248,26 +224,7 @@ A number of extensions use service manager callbacks and service timers to imple
 * [slack-ruby-bot-server-events](https://github.com/slack-ruby/slack-ruby-bot-server-events): Easily handle Slack slash commands, interactive buttons and events.
 * [slack-ruby-bot-server-mailchimp](https://github.com/slack-ruby/slack-ruby-bot-server-mailchimp): Subscribes new bot users to a Mailchimp mailing list.
 * [slack-ruby-bot-server-stripe](https://github.com/slack-ruby/slack-ruby-bot-server-stripe): Enables paid bots with trial periods and commerce through Stripe.
-
-#### Server Class
-
-You can override the server class to handle additional events, and configure the service to use it.
-
-```ruby
-class MyServer < SlackRubyBotServer::Server
-  on :hello do |client, data|
-    # connected to Slack
-  end
-
-  on :channel_joined do |client, data|
-    # the bot joined a channel in data.channel['id']
-  end
-end
-
-SlackRubyBotServer.configure do |config|
-  config.server_class = MyServer
-end
-```
+* [slack-ruby-bot-server-rtm](https://github.com/slack-ruby/slack-ruby-bot-server-rtm): Create RTM Slack bots.
 
 #### Service Class
 
@@ -302,15 +259,16 @@ end
 
 ### Access Tokens
 
-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.
+By default the implementation of [Team](lib/slack-ruby-bot-server/models/team) stores a `bot_access_token` as `token` (for backwards compatibility), and `activated_user_access_token` as the token with all the requested OAuth scopes.
+
+### Sample Bots Using Slack Ruby Bot Server
 
-1) Configure your app to require additional scopes in Slack API under _OAuth_, _Permissions_
-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`.
+#### Slack Bots with Granular Permissions
 
-You can see a sample implementation in [slack-sup#3a497b](https://github.com/dblock/slack-sup/commit/3a497b436d25d3a7738562655cda64b180ae0096).
+* [slack-ruby-bot-server-events-sample](https://github.com/slack-ruby/slack-ruby-bot-server-events-sample), a generic sample
+* [slack-rails-bot-starter](https://github.com/CrazyOptimist/slack-rails-bot-starter), an all-in-one Rails starter kit
 
-### Example Bots Using Slack Ruby Bot Server
+#### Legacy Slack Bots
 
 * [slack-ruby-bot-server-sample](https://github.com/slack-ruby/slack-ruby-bot-server-sample), a generic sample
 * [slack-sup](https://github.com/dblock/slack-sup), see [sup.playplay.io](https://sup.playplay.io)
@@ -320,7 +278,6 @@ You can see a sample implementation in [slack-sup#3a497b](https://github.com/dbl
 * [slack-api-explorer](https://github.com/slack-ruby/slack-api-explorer), see [api-explorer.playplay.io](https://shell.playplay.io)
 * [slack-strava](https://github.com/dblock/slack-strava), see [slava.playplay.io](https://slava.playplay.io)
 * [slack-arena](https://github.com/dblock/slack-arena), see [arena.playplay.io](https://arena.playplay.io)
-* [slack-rails-bot-starter](https://github.com/CrazyOptimist/slack-rails-bot-starter), an all-in-one rails starter kit built on top of the slack-ruby-bot-server and the slack-ruby-bot-server-events
 
 ### Copyright & License
 

UPGRADING.md

@@ -1,6 +1,20 @@
 Upgrading Slack-Ruby-Bot-Server
 ===============================
 
+### Upgrading to >= 1.0.0
+
+#### Extracted RealTime (Legacy) Support
+
+New slack apps may no longer access RTM. Classic Slack apps can no longer be submitted to the app directory as of December 4th, 2020. In preparation for these changes slack-ruby-bot-server no longer includes RTM components by default. These have been extracted to a new gem [slack-ruby-bot-server-rtm](https://github.com/slack-ruby/slack-ruby-bot-server-rtm).
+
+To upgrade an existing classic Slack app that uses slack-ruby-bot-server do the following.
+
+1. Add `slack-ruby-bot-server-rtm` as an additional dependency.
+2. Replace any reference to `SlackRubyBotServer::Server` to `SlackRubyBotServer::RealTime::Server`.
+3. Replace any `require 'slack-ruby-bot-server/rspec'` with `require 'slack-ruby-bot-server-rtm/rspec'`.
+
+Existing RTM Slack bots will continue working and be listed in the Slack App Directory. On December 4th, 2020 Slack will no longer accept resubmissions from apps that are not using granular permissions. On November 18, 2021 Slack will start delisting apps that have not migrated to use granular permissions. Use [slack-ruby-bot-server-events](https://github.com/slack-ruby/slack-ruby-bot-server-events) to create a Slack bot with granular permissions. See [migration](https://api.slack.com/authentication/migration) for more details.
+
 ### Upgrading to >= 0.11.0
 
 #### Removed Legacy Migrations