slackify 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca58d1a63e649165df6caccc7092ee6ab04ee2fa9edaa5b3225a156cb66d4566
-  data.tar.gz: 3d3ae1cdd0f6f78ba32361fa61d858402968643819359fa363b15f4ee1547b49
+  metadata.gz: e158dfddb3b113177499b3247dbc9a4a7a4f9fff55f87ecafb21064aa4549325
+  data.tar.gz: cb03ce87203fc97ca0f4d7a728f25b6f729288e539b1530b39e6d51f59f6020a
 SHA512:
-  metadata.gz: 51f0928b97da9b9839317b550ae616299ed4fb6692ed020f6ebfd6e0f14e0e222cc34aa7d225bfb0dc197441d6bb7988e3b2318369efe44814a0a60c4837770c
-  data.tar.gz: 3c7a7e4d3e394c0024df2523716f92a6e556f43e6cb00e620257d0148c2f889daabb4dbd67db3a977e3524e8b0fc05f5f3acaa2f4bb78e734fa062f3a73c9f8e
+  metadata.gz: '093e9a1f4ab6e37c0020fb699d45ed392922477a195d72ba415ce702b3c2096663b6beba81364e61aae513ce0e3693f5463bd6a36a5ba48d2bc9888e4a48c856'
+  data.tar.gz: a0f3caca091ceef0e50e84e5d1a6b6c139dcf7de5982babec1b43e1f21d1376b1bdb76f223b4e43b4b9ddf925c66fb7906bf80aa5f9d3dc9df8e85e1631f5954

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## V0.3.0
+
+* Add code documentation and improve exception message
+* Add whitelisting of bot ids in the configuration through `whitelisted_bot_ids=`
+* Refactored Handler configuration into `Slackify::Router` and `Slackify::Handlers::Factory`
+* Improved testing
+* Remove the need to perform `Slackify.load_handler`
+* **Breaking change:** Given that we now load the handlers on `Slack.configure`, the configuration step done in `config/application.rb` will have to be done in an initializer to have all the handler class loaded. 
+
 ## V0.2.0
 
 Update `custom_event_subtype_handlers` to `custom_message_subtype_handlers` and add support for `custom_event_type_handlers`. This is a breaking change since we rename the field that was previously used. To fix, update any calls from `custom_event_subtype_handlers` to `custom_message_subtype_handlers` and you should be good to go.

data/README.md

@@ -1,4 +1,4 @@
-# Slackify [![Build Status](https://travis-ci.org/jusleg/slackify.svg?branch=master)](https://travis-ci.org/jusleg/slackify) [![Gem Version](https://badge.fury.io/rb/slackify.svg)](https://badge.fury.io/rb/slackify)
+# Slackify [![Build Status](https://travis-ci.org/jusleg/slackify.svg?branch=master)](https://travis-ci.org/jusleg/slackify) [![Gem Version](https://badge.fury.io/rb/slackify.svg)](https://badge.fury.io/rb/slackify) ![Gem downloads](https://img.shields.io/gem/dt/slackify)
 
 Slackify is a gem that allows to build slackbots on Rails using the [Event API](https://api.slack.com/events-api) from Slack.
 
@@ -218,29 +218,45 @@ First, you'll need to create a new app on slack. Head over to [slack api](https:
     Under the setting section, click "install app" and proceed to install the app to the workspace. Once the app is installed, go back to the "install app" page and copy the Bot User OAuth Access Token.
 
 6. **Configure Slackify**
+Add a new initializer with the following code
+
 ```ruby
+# config/initializers/slackify.rb
 Slackify.configure do |config|
   config.slack_bot_token = "xoxb-sdkjlkjsdflsd..."
   config.slack_secret_token = "1234dummysecret"
 end
 ```
 
-7. **Add an initializer**
+7. **Define handlers specific subtypes** (Optional)
+You can set custom [message subtype](https://api.slack.com/events/message) handlers or custom [event type](https://api.slack.com/events) handlers inside your configuration
+
 ```ruby
 # config/initializers/slackify.rb
-Slackify.load_handlers
+Slackify.configure do |config|
+  config.slack_bot_token = "xoxb-sdkjlkjsdflsd..."
+  config.slack_secret_token = "1234dummysecret"
+  config.custom_message_subtype_handlers = {
+    file_share: ImageHandler,
+    channel_join: JoinHandler,
+    ...
+  }
+  config.custom_event_type_handlers = {
+    app_mention: ...
+  }
+end
 ```
 
-8. **Define handlers specific subtypes** (Optional)
+8. **Handle bot messages** (Highly optional)
+If you want your bot to accept other bot messages (which you probably should not do), you can. In the configuration step, you can set an array of whitelisted bot ids.
 
 ```ruby
 # config/initializers/slackify.rb
-Slackify.load_handlers
-Slackify.configuration.custom_message_subtype_handlers = {
-  file_share: ImageHandler,
-  channel_join: JoinHandler,
-  ...
-}
+Slackify.configure do |config|
+...
+config.whitelisted_bot_ids = ['abc123', 'def456']
+...
+end
 ```
 
 **At this point, you are ready to go 😄**

data/app/controllers/slackify/slack_controller.rb

@@ -59,10 +59,13 @@ module Slackify
         return
       end
 
-      return if params[:event][:subtype] == "bot_message" || params[:event].key?(:bot_id) || params[:event][:hidden]
+      return if (params[:event][:subtype] == "bot_message" ||
+        params[:event].key?(:bot_id) ||
+        params[:event][:hidden]) &&
+                Slackify.configuration.whitelisted_bot_ids.exclude?(params.dig(:event, :bot_id))
 
       command = params[:event][:text]
-      Slackify.configuration.handlers.call_command(command, params[:slack])
+      Slackify::Router.call_command(command, params[:slack])
     rescue RuntimeError => e
       raise e unless e.message == "Component not found for a command message"
     end
@@ -76,7 +79,7 @@ module Slackify
       class_name, method_name = callback_id.split('#')
       class_name = class_name.camelize
 
-      raise Exceptions::HandlerNotSupported, class_name unless
+      raise Exceptions::HandlerNotSupported, "#{class_name} is not a subclass of Slackify::Handlers::Base" unless
         Handlers::Base.supported_handlers.include?(class_name)
 
       class_name.constantize.method(method_name)
@@ -85,7 +88,7 @@ module Slackify
     def verify_handler_slash_permission(handler_class, handler_method)
       handler_class = handler_class.camelize
 
-      raise Exceptions::HandlerNotSupported, handler_class unless
+      raise Exceptions::HandlerNotSupported, "#{handler_class} is not a subclass of Slackify::Handlers::Base" unless
         Handlers::Base.supported_handlers.include?(handler_class)
 
       handler = handler_class.constantize

data/lib/slackify.rb

@@ -4,6 +4,7 @@ require 'slackify/configuration'
 require 'slackify/engine'
 require 'slackify/exceptions'
 require 'slackify/handlers'
+require 'slackify/router'
 
 module Slackify
   class << self
@@ -19,9 +20,5 @@ module Slackify
     def configure
       yield(configuration)
     end
-
-    def load_handlers
-      @configuration.handlers = Handlers::Configuration.new
-    end
   end
 end

data/lib/slackify/configuration.rb

@@ -3,42 +3,75 @@
 require 'slack'
 
 module Slackify
+  # Where the configuration for Slackify lives
   class Configuration
     attr_reader :custom_message_subtype_handlers, :slack_bot_token, :unhandled_handler, :custom_event_type_handlers
-    attr_accessor :handlers, :slack_secret_token, :slack_client
+    attr_accessor :handlers, :slack_secret_token, :slack_client, :whitelisted_bot_ids
 
     def initialize
       @slack_bot_token = nil
       @slack_secret_token = nil
-      @handlers = nil
+      @handlers = generate_handlers
       @slack_client = nil
       @custom_message_subtype_handlers = {}
       @custom_event_type_handlers = {}
       @unhandled_handler = Handlers::UnhandledHandler
+      @whitelisted_bot_ids = []
     end
 
+    # Set your own unhandled handler
     def unhandled_handler=(handler)
-      raise Exceptions::InvalidHandler, "#{handler.class} is not a subclass of Slackify::Handlers::Base" unless
+      raise HandlerNotSupported, "#{handler.class} is not a subclass of Slackify::Handlers::Base" unless
         handler < Handlers::Base
 
       @unhandled_handler = handler
     end
 
+    # Remove unhandled handler. The bot will not reply if the message doesn't
+    # match any regex
     def remove_unhandled_handler
       @unhandled_handler = nil
     end
 
+    # Set the token that we will use to connect to slack
     def slack_bot_token=(token)
       @slack_bot_token = token
       @slack_client = Slack::Web::Client.new(token: token).freeze
     end
 
+    # Set a handler for a specific message subtype
+    # That handler will have to implement `self.handle_event(params)`
+    # see https://api.slack.com/events/message
     def custom_message_subtype_handlers=(event_subtype_hash)
       @custom_message_subtype_handlers = event_subtype_hash.with_indifferent_access
     end
 
+    # Set a handler for a event type
+    # That handler will have to implement `self.handle_event(params)`
+    # see https://api.slack.com/events
     def custom_event_type_handlers=(event_type_hash)
       @custom_event_type_handlers = event_type_hash.with_indifferent_access
     end
+
+    private
+
+    # Convert a hash to a list of lambda functions that will be called to handle
+    # the user messages
+    def generate_handlers
+      generated_handlers = []
+      read_handlers_yaml.each do |handler_hash|
+        handler = Handlers::Factory.for(handler_hash)
+        generated_handlers << handler
+      end
+
+      generated_handlers
+    end
+
+    # Reads the config/handlers.yml configuration
+    def read_handlers_yaml
+      raise 'config/handlers.yml does not exist' unless File.exist?("#{Rails.root}/config/handlers.yml")
+
+      YAML.load_file("#{Rails.root}/config/handlers.yml") || []
+    end
   end
 end

data/lib/slackify/engine.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Slackify
+  # Makes the whole thing work. Adds the routes for slackify.
   class Engine < Rails::Engine
     isolate_namespace Slackify
   end

data/lib/slackify/exceptions.rb

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
 
 module Slackify
+  # When things go boom, we need these.
   module Exceptions
+    # You tried to call a class that was not extending the base handler
     class HandlerNotSupported < StandardError; end
+    # You handler is failing validations
     class InvalidHandler < StandardError; end
+    # The handler method was not whitelisted to be a slash command
     class MissingSlashPermission < StandardError; end
   end
 end

data/lib/slackify/handlers.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'handlers/base'
-require_relative 'handlers/configuration'
+require_relative 'handlers/factory'
 require_relative 'handlers/unhandled_handler'
 require_relative 'handlers/validator'
 

data/lib/slackify/handlers/base.rb

@@ -2,16 +2,25 @@
 
 module Slackify
   module Handlers
+    # Base handler class that any user defined handlers must inherit from
     class Base
       @@supported_handlers = []
 
       class << self
         attr_reader :allowed_slash_methods
 
+        # Get the slack client that you can use to perform slack api calls
+        # @see https://github.com/slack-ruby/slack-ruby-client
         def slack_client
           Slackify.configuration.slack_client
         end
 
+        # Enables a method to be called for a slash command.
+        #
+        # More context:
+        # Slash commands have extra validations. To call a slash command, it
+        # needs to call a method on a supported handler and that handler needs
+        # to explicitly specify which methods are for slash command.
         def allow_slash_method(element)
           if @allowed_slash_methods
             @allowed_slash_methods.push(*element)
@@ -20,10 +29,14 @@ module Slackify
           end
         end
 
+        # Any class inheriting from Slackify::Handler::Base will be added to
+        # the list of supported handlers
         def inherited(subclass)
           @@supported_handlers.push(subclass.to_s)
         end
 
+        # Show a list of the handlers supported by the app. Since we do
+        # metaprogramming, we want to ensure we can only call defined handlers
         def supported_handlers
           @@supported_handlers
         end

data/lib/slackify/handlers/factory.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Slackify
+  module Handlers
+    # Creates the handler structs
+    class Factory
+      def self.for(configuration)
+        Validator.verify_handler_integrity(configuration)
+
+        handler = OpenStruct.new
+        handler.name = configuration.keys.first
+        handler.commands = []
+
+        configuration[handler.name]['commands']&.each do |command|
+          built_command = OpenStruct.new
+          built_command.regex = command['regex']
+          built_command.handler = handler.name.camelize.constantize.method(command['action'])
+          built_command.description = command['description']
+          handler.commands << built_command.freeze
+        end
+
+        handler.commands.freeze
+        handler.freeze
+      end
+    end
+  end
+end

data/lib/slackify/handlers/unhandled_handler.rb

@@ -2,6 +2,10 @@
 
 module Slackify
   module Handlers
+    # Default handler for any text message that is not handler by other handlers
+    # This can easily be replaced by setting you own unhandled handler when
+    # configuring slackify. Use `#unhandled_handler=` to set it. Your handler
+    # must implement a `self.unhandled` method.
     class UnhandledHandler < Base
       def self.unhandled(params)
         slack_client.chat_postMessage(

data/lib/slackify/handlers/validator.rb

@@ -2,7 +2,10 @@
 
 module Slackify
   module Handlers
+    # Simple validator for handlers. It will blow your app up on the
+    # configuration step instead of crashing when handling production requests.
     class Validator
+      # Checks if your handler hash is valid. It's pass or raise 🧨💥
       def self.verify_handler_integrity(handler)
         handler_name = handler.keys.first
         handler_class = handler_name.camelize.constantize

data/lib/slackify/router.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Slackify
+  # In charge of routing a message to its proper handler
+  class Router
+    class << self
+      # List all available commands
+      def all_commands
+        Slackify.configuration.handlers.collect(&:commands).flatten
+      end
+
+      # Find the matching command based on the message string
+      def matching_command(message)
+        all_commands.each { |command| return command if command.regex.match? message }
+        nil
+      end
+
+      # Call command based on message string
+      def call_command(message, params)
+        command = matching_command(message)
+        if command.nil?
+          return unless Slackify.configuration.unhandled_handler
+
+          Slackify.configuration.unhandled_handler.unhandled(params)
+        else
+          new_params = params.merge(command_arguments: command.regex.match(message).named_captures)
+          command.handler.call(new_params)
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: slackify
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Justin Leger
@@ -114,9 +114,10 @@ files:
 - lib/slackify/exceptions.rb
 - lib/slackify/handlers.rb
 - lib/slackify/handlers/base.rb
-- lib/slackify/handlers/configuration.rb
+- lib/slackify/handlers/factory.rb
 - lib/slackify/handlers/unhandled_handler.rb
 - lib/slackify/handlers/validator.rb
+- lib/slackify/router.rb
 homepage: https://github.com/jusleg/slackify
 licenses:
 - MIT

data/lib/slackify/handlers/configuration.rb

@@ -1,94 +0,0 @@
-# frozen_string_literal: true
-
-require 'ostruct'
-
-module Slackify
-  module Handlers
-    class Configuration
-      attr_reader :bot_id
-      attr_accessor :handlers
-      delegate :each, to: :@handlers
-
-      def initialize
-        @handlers = []
-
-        read_handlers_yaml.each do |handler_yaml|
-          handler = generate_handler_from_yaml(handler_yaml)
-          @handlers << handler
-        end
-
-        environment_configurations
-      end
-
-      def all_commands
-        @handlers.collect(&:commands).flatten
-      end
-
-      def matching_command(message)
-        all_commands.each { |command| return command if command.regex.match? message }
-        nil
-      end
-
-      def call_command(message, params)
-        return if params.dig(:event, :user) == @bot_id || params.dig(:event, :message, :user) == @bot_id
-
-        command = matching_command(message)
-        if command.nil?
-          return unless Slackify.configuration.unhandled_handler
-
-          Slackify.configuration.unhandled_handler.unhandled(params)
-        else
-          new_params = params.merge(command_arguments: command.regex.match(message).named_captures)
-          command.handler.call(new_params)
-        end
-      end
-
-      def bot_auth_test
-        @bot_id = Slackify.configuration.slack_client.auth_test.fetch('user_id')
-        Rails.logger.debug("[Slackify] Bot successfully authenticated to Slack")
-        true
-      rescue KeyError
-        raise "[Slackify] The bot did not successfully authenticate to Slack"
-      end
-
-      private
-
-      def environment_configurations
-        if %w(production staging development).exclude?(Rails.env) || skip_auth?
-          @bot_id = 'dummy_bot_id'
-        else
-          bot_auth_test
-        end
-      end
-
-      def skip_auth?
-        ENV['SLACKIFY_AUTH_SKIP'] == '1'
-      end
-
-      def read_handlers_yaml
-        raise 'config/handlers.yml does not exist' unless File.exist?("#{Rails.root}/config/handlers.yml")
-
-        YAML.load_file("#{Rails.root}/config/handlers.yml") || []
-      end
-
-      def generate_handler_from_yaml(handler_yaml)
-        Validator.verify_handler_integrity(handler_yaml)
-
-        handler = OpenStruct.new
-        handler.name = handler_yaml.keys.first
-        handler.commands = []
-
-        handler_yaml[handler.name]['commands']&.each do |command|
-          built_command = OpenStruct.new
-          built_command.regex = command['regex']
-          built_command.handler = handler.name.camelize.constantize.method(command['action'])
-          built_command.description = command['description']
-          handler.commands << built_command.freeze
-        end
-
-        handler.commands.freeze
-        handler.freeze
-      end
-    end
-  end
-end