bolt_rb 0.1.0

data/lib/bolt_rb/handlers/action_handler.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module BoltRb
+  module Handlers
+    # Handler for Slack interactive component actions (buttons, select menus, etc.)
+    #
+    # This handler provides the `action` DSL for matching block_actions payloads.
+    # Block actions are triggered when users interact with interactive components
+    # like buttons, overflow menus, date pickers, and select menus in messages
+    # or modals.
+    #
+    # @example Basic button handler
+    #   class ApproveHandler < BoltRb::ActionHandler
+    #     action 'approve_button'
+    #
+    #     def handle
+    #       ack
+    #       say("Approved by <@#{user}>!")
+    #     end
+    #   end
+    #
+    # @example Handler with block_id filter
+    #   class RequestApprovalHandler < BoltRb::ActionHandler
+    #     action 'approve', block_id: 'approval_block'
+    #
+    #     def handle
+    #       ack
+    #       # Handle approval request
+    #     end
+    #   end
+    #
+    # @example Regex-based action matching
+    #   class DynamicButtonHandler < BoltRb::ActionHandler
+    #     action /^approve_request_/
+    #
+    #     def handle
+    #       ack
+    #       request_id = action_id.gsub('approve_request_', '')
+    #       # Process the request
+    #     end
+    #   end
+    class ActionHandler < Base
+      class << self
+        # Configures which action_id this handler responds to
+        #
+        # @param action_id [String, Regexp] The action_id to match (exact string or regex)
+        # @param block_id [String, Regexp, nil] Optional block_id filter for more specific matching
+        # @return [void]
+        #
+        # @example Match exact action_id
+        #   action 'approve_button'
+        #
+        # @example Match with block_id
+        #   action 'approve_button', block_id: 'approval_block'
+        #
+        # @example Match action_id pattern
+        #   action /^approve_/
+        def action(action_id, block_id: nil)
+          @matcher_config = {
+            type: :action,
+            action_id: action_id,
+            block_id: block_id
+          }
+        end
+
+        # Determines if this handler matches the given payload
+        #
+        # Checks if the payload is a block_actions type and if any of the
+        # actions in the payload match the configured action_id and optional block_id.
+        #
+        # @param payload [Hash] The incoming Slack block_actions payload
+        # @return [Boolean] true if this handler should process the action
+        def matches?(payload)
+          return false unless matcher_config
+          return false unless payload['type'] == 'block_actions'
+
+          actions = payload['actions'] || []
+          actions.any? do |action|
+            action_matches?(action) && block_matches?(action)
+          end
+        end
+
+        private
+
+        # Checks if the action's action_id matches the configured pattern
+        #
+        # @param action [Hash] A single action from the payload
+        # @return [Boolean] true if action_id matches
+        def action_matches?(action)
+          if matcher_config[:action_id].is_a?(Regexp)
+            matcher_config[:action_id].match?(action['action_id'])
+          else
+            action['action_id'] == matcher_config[:action_id]
+          end
+        end
+
+        # Checks if the action's block_id matches the configured pattern
+        #
+        # If no block_id is configured, this always returns true (no filtering).
+        #
+        # @param action [Hash] A single action from the payload
+        # @return [Boolean] true if block_id matches or no block_id filter is set
+        def block_matches?(action)
+          return true if matcher_config[:block_id].nil?
+
+          if matcher_config[:block_id].is_a?(Regexp)
+            matcher_config[:block_id].match?(action['block_id'])
+          else
+            action['block_id'] == matcher_config[:block_id]
+          end
+        end
+      end
+
+      # Returns the first action from the payload
+      #
+      # Block actions payloads can contain multiple actions, but typically
+      # only one action is triggered at a time. This returns the first action.
+      #
+      # @return [Hash, nil] The action hash containing action_id, value, etc.
+      def action
+        payload['actions']&.first
+      end
+
+      # Returns the action_id from the triggered action
+      #
+      # @return [String, nil] The action_id
+      def action_id
+        action&.dig('action_id')
+      end
+
+      # Returns the value from the triggered action
+      #
+      # For buttons this is the button's value. For select menus this is
+      # the selected option's value.
+      #
+      # @return [String, nil] The action value
+      def action_value
+        action&.dig('value')
+      end
+
+      # Returns the block_id from the triggered action
+      #
+      # @return [String, nil] The block_id
+      def block_id
+        action&.dig('block_id')
+      end
+
+      # Returns the trigger_id for opening modals
+      #
+      # Slack provides a trigger_id with interactive actions that can be used
+      # to open modals within 3 seconds of receiving the action.
+      #
+      # @return [String, nil] The trigger_id for views.open
+      def trigger_id
+        payload['trigger_id']
+      end
+    end
+  end
+
+  # Top-level alias for convenience
+  ActionHandler = Handlers::ActionHandler
+end

data/lib/bolt_rb/handlers/base.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module BoltRb
+  module Handlers
+    # Base class for all Slack event handlers.
+    #
+    # This provides the common interface and middleware execution that all
+    # handler types (Event, Command, Action, Shortcut) inherit from.
+    #
+    # Subclasses should:
+    # - Override .matches?(payload) to define matching logic
+    # - Override #handle to implement the handler behavior
+    # - Optionally use .use(middleware) to add handler-specific middleware
+    #
+    # @example Creating a custom handler
+    #   class MyHandler < BoltRb::Handlers::Base
+    #     use MyCustomMiddleware
+    #
+    #     def self.matches?(payload)
+    #       payload.dig('event', 'type') == 'message'
+    #     end
+    #
+    #     def handle
+    #       say("Received your message!")
+    #     end
+    #   end
+    class Base
+      class << self
+        # Configuration for matching this handler to payloads
+        # Subclasses should set this to define their matching criteria
+        #
+        # @return [Object, nil] The matcher configuration
+        attr_reader :matcher_config
+
+        # Returns the middleware stack for this handler class
+        #
+        # @return [Array<Class>] Array of middleware classes
+        def middleware_stack
+          @middleware_stack ||= []
+        end
+
+        # Adds middleware to this handler's stack
+        #
+        # Middleware is executed in the order added, wrapping the #handle method.
+        # Each middleware should call yield to continue the chain.
+        #
+        # @param middleware_class [Class] The middleware class to add
+        # @return [void]
+        #
+        # @example Adding middleware
+        #   class MyHandler < Base
+        #     use LoggingMiddleware
+        #     use AuthenticationMiddleware
+        #   end
+        def use(middleware_class)
+          middleware_stack << middleware_class
+        end
+
+        # Determines if this handler matches the given payload
+        #
+        # Base implementation always returns false. Subclasses should override
+        # this to implement their matching logic.
+        #
+        # @param _payload [Hash] The incoming Slack payload
+        # @return [Boolean] true if this handler should process the payload
+        def matches?(_payload)
+          false
+        end
+
+        # Hook called when a class inherits from Base
+        #
+        # Ensures each subclass gets its own independent middleware stack
+        # and registers the handler with the global router.
+        #
+        # @param subclass [Class] The inheriting class
+        # @return [void]
+        def inherited(subclass)
+          super
+          subclass.instance_variable_set(:@middleware_stack, [])
+          # Auto-register with the global router
+          BoltRb.router.register(subclass)
+        end
+      end
+
+      # @return [Context] The context object for this handler invocation
+      attr_reader :context
+
+      # Creates a new handler instance
+      #
+      # @param context [Context] The context containing payload, client, and ack
+      def initialize(context)
+        @context = context
+      end
+
+      # Returns the raw payload from the context
+      #
+      # @return [Hash] The Slack event payload
+      def payload
+        context.payload
+      end
+
+      # Returns the Slack Web API client
+      #
+      # @return [Slack::Web::Client] The API client
+      def client
+        context.client
+      end
+
+      # Returns the user ID from the context
+      #
+      # @return [String, nil] The user ID
+      def user
+        context.user
+      end
+
+      # Returns the channel ID from the context
+      #
+      # @return [String, nil] The channel ID
+      def channel
+        context.channel
+      end
+
+      # Posts a message to the channel
+      #
+      # Delegates to Context#say
+      #
+      # @param message [String, Hash] The message to post
+      # @return [Hash] The Slack API response
+      def say(message)
+        context.say(message)
+      end
+
+      # Acknowledges the event
+      #
+      # Delegates to Context#ack
+      #
+      # @param response [String, Hash, nil] Optional response to include
+      # @return [void]
+      def ack(response = nil)
+        context.ack(response)
+      end
+
+      # Responds using the response_url
+      #
+      # Delegates to Context#respond
+      #
+      # @param message [String, Hash] The message to send
+      # @return [Net::HTTPResponse, nil] The HTTP response
+      def respond(message)
+        context.respond(message)
+      end
+
+      # Executes this handler
+      #
+      # Runs the middleware stack, then calls #handle at the end of the chain.
+      #
+      # @return [void]
+      def call
+        run_middleware { handle }
+      end
+
+      # The main handler logic
+      #
+      # Subclasses must override this method to implement their behavior.
+      #
+      # @raise [NotImplementedError] Always raises in the base class
+      def handle
+        raise NotImplementedError, 'Subclasses must implement #handle'
+      end
+
+      private
+
+      # Executes the middleware chain, then the given block
+      #
+      # Creates a recursive chain where each middleware can call yield
+      # to invoke the next middleware (or the final block).
+      #
+      # @yield The block to execute at the end of the chain
+      # @return [void]
+      def run_middleware(&block)
+        chain = self.class.middleware_stack.dup
+        run_next = proc do
+          if chain.empty?
+            block.call
+          else
+            middleware = chain.shift.new
+            middleware.call(context) { run_next.call }
+          end
+        end
+        run_next.call
+      end
+    end
+  end
+end

data/lib/bolt_rb/handlers/command_handler.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module BoltRb
+  module Handlers
+    # Handler for Slack slash commands (/deploy, /help, etc.)
+    #
+    # This handler provides the `command` DSL for matching slash command invocations.
+    # Slash commands have a different payload structure than events, with fields like
+    # `user_id`, `channel_id`, and `trigger_id` at the top level.
+    #
+    # @example Basic command handler
+    #   class DeployHandler < BoltRb::CommandHandler
+    #     command '/deploy'
+    #
+    #     def handle
+    #       ack
+    #       say("Deploying: #{command_text}")
+    #     end
+    #   end
+    #
+    # @example Command with modal
+    #   class SettingsHandler < BoltRb::CommandHandler
+    #     command '/settings'
+    #
+    #     def handle
+    #       ack
+    #       client.views_open(
+    #         trigger_id: trigger_id,
+    #         view: { type: 'modal', ... }
+    #       )
+    #     end
+    #   end
+    class CommandHandler < Base
+      class << self
+        # Configures which slash command this handler responds to
+        #
+        # @param command_name [String] The slash command to handle (e.g., '/deploy')
+        # @return [void]
+        #
+        # @example
+        #   command '/deploy'
+        def command(command_name)
+          @matcher_config = {
+            type: :command,
+            command: command_name
+          }
+        end
+
+        # Determines if this handler matches the given payload
+        #
+        # Checks if the payload's command field matches the configured command.
+        #
+        # @param payload [Hash] The incoming Slack command payload
+        # @return [Boolean] true if this handler should process the command
+        def matches?(payload)
+          return false unless matcher_config
+
+          payload['command'] == matcher_config[:command]
+        end
+      end
+
+      # Returns the slash command that was invoked
+      #
+      # @return [String] The command name (e.g., '/deploy')
+      def command_name
+        payload['command']
+      end
+
+      # Returns the text provided after the command
+      #
+      # For `/deploy production --force`, this returns "production --force"
+      #
+      # @return [String, nil] The text argument or nil if none provided
+      def command_text
+        payload['text']
+      end
+
+      # Returns the command parameters as a hash
+      #
+      # @return [Hash] Hash containing :text key with command text
+      def params
+        { text: command_text }
+      end
+
+      # Returns the trigger_id for opening modals
+      #
+      # Slack provides a trigger_id with slash commands that can be used
+      # to open modals within 3 seconds of receiving the command.
+      #
+      # @return [String, nil] The trigger_id for views.open
+      def trigger_id
+        payload['trigger_id']
+      end
+
+      # Returns the user ID who invoked the command
+      #
+      # Overrides Base#user because slash command payloads use 'user_id'
+      # instead of nested event.user structure.
+      #
+      # @return [String, nil] The user ID
+      def user
+        payload['user_id'] || super
+      end
+
+      # Returns the channel ID where the command was invoked
+      #
+      # Overrides Base#channel because slash command payloads use 'channel_id'
+      # instead of nested event.channel structure.
+      #
+      # @return [String, nil] The channel ID
+      def channel
+        payload['channel_id'] || super
+      end
+    end
+  end
+
+  # Top-level alias for convenience
+  CommandHandler = Handlers::CommandHandler
+end

data/lib/bolt_rb/handlers/event_handler.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module BoltRb
+  module Handlers
+    # Handler for Slack events (message, app_mention, reaction_added, etc.)
+    #
+    # This handler provides the `listen_to` DSL for matching event types
+    # and optionally filtering by text patterns.
+    #
+    # @example Basic message handler
+    #   class GreetingHandler < BoltRb::EventHandler
+    #     listen_to :message
+    #
+    #     def handle
+    #       say("Hello, #{user}!")
+    #     end
+    #   end
+    #
+    # @example Handler with pattern matching
+    #   class HelloHandler < BoltRb::EventHandler
+    #     listen_to :message, pattern: /hello/i
+    #
+    #     def handle
+    #       say("Hello to you too!")
+    #     end
+    #   end
+    #
+    # @example App mention handler
+    #   class MentionHandler < BoltRb::EventHandler
+    #     listen_to :app_mention
+    #
+    #     def handle
+    #       say("You mentioned me in #{channel}!")
+    #     end
+    #   end
+    class EventHandler < Base
+      class << self
+        # Configures which event type this handler responds to
+        #
+        # @param event_type [Symbol, String] The Slack event type to listen for
+        #   (e.g., :message, :app_mention, :reaction_added)
+        # @param pattern [Regexp, nil] Optional regex pattern to match against
+        #   the event's text field
+        # @return [void]
+        #
+        # @example Listen to all messages
+        #   listen_to :message
+        #
+        # @example Listen to messages matching a pattern
+        #   listen_to :message, pattern: /help/i
+        def listen_to(event_type, pattern: nil)
+          @matcher_config = {
+            type: :event,
+            event_type: event_type,
+            pattern: pattern
+          }
+        end
+
+        # Determines if this handler matches the given payload
+        #
+        # Checks the event type and optionally the text pattern.
+        #
+        # @param payload [Hash] The incoming Slack event payload
+        # @return [Boolean] true if this handler should process the event
+        def matches?(payload)
+          return false unless matcher_config
+
+          event = payload['event']
+          return false unless event
+          return false unless event['type'].to_s == matcher_config[:event_type].to_s
+
+          if matcher_config[:pattern]
+            return false if event['text'].nil?
+            return matcher_config[:pattern].match?(event['text'])
+          end
+
+          true
+        end
+      end
+
+      # Returns the event portion of the payload
+      #
+      # @return [Hash, nil] The event data
+      def event
+        payload['event']
+      end
+
+      # Returns the text content of the event
+      #
+      # @return [String, nil] The message text
+      def text
+        event&.dig('text')
+      end
+
+      # Returns the thread timestamp if this message is in a thread
+      #
+      # @return [String, nil] The thread_ts value
+      def thread_ts
+        event&.dig('thread_ts')
+      end
+
+      # Returns the message timestamp
+      #
+      # @return [String, nil] The ts value
+      def ts
+        event&.dig('ts')
+      end
+    end
+  end
+
+  # Top-level alias for convenience
+  EventHandler = Handlers::EventHandler
+end