bolt_rb 0.1.0

data/lib/bolt_rb/handlers/shortcut_handler.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module BoltRb
+  module Handlers
+    # Handler for Slack shortcuts (global shortcuts and message shortcuts)
+    #
+    # This handler provides the `shortcut` DSL for matching shortcut payloads.
+    # Global shortcuts are triggered from the lightning bolt menu in Slack,
+    # while message shortcuts appear in the context menu of messages.
+    #
+    # @example Global shortcut handler
+    #   class CreateTicketHandler < BoltRb::ShortcutHandler
+    #     shortcut 'create_ticket'
+    #
+    #     def handle
+    #       ack
+    #       # Open a modal with views.open using trigger_id
+    #     end
+    #   end
+    #
+    # @example Message shortcut handler
+    #   class QuoteMessageHandler < BoltRb::ShortcutHandler
+    #     shortcut 'quote_message'
+    #
+    #     def handle
+    #       ack
+    #       text = message_text
+    #       # Do something with the quoted message
+    #     end
+    #   end
+    #
+    # @example Regex-based shortcut matching
+    #   class CreateHandler < BoltRb::ShortcutHandler
+    #     shortcut /^create_/
+    #
+    #     def handle
+    #       ack
+    #       # Handle any shortcut starting with 'create_'
+    #     end
+    #   end
+    class ShortcutHandler < Base
+      # Valid shortcut payload types
+      # 'shortcut' is a global shortcut (from lightning bolt menu)
+      # 'message_action' is a message shortcut (from message context menu)
+      SHORTCUT_TYPES = %w[shortcut message_action].freeze
+
+      class << self
+        # Configures which callback_id this handler responds to
+        #
+        # @param callback_id [String, Regexp] The callback_id to match (exact string or regex)
+        # @return [void]
+        #
+        # @example Match exact callback_id
+        #   shortcut 'create_ticket'
+        #
+        # @example Match callback_id pattern
+        #   shortcut /^create_/
+        def shortcut(callback_id)
+          @matcher_config = {
+            type: :shortcut,
+            callback_id: callback_id
+          }
+        end
+
+        # Determines if this handler matches the given payload
+        #
+        # Checks if the payload is a shortcut or message_action type and if the
+        # callback_id matches the configured pattern.
+        #
+        # @param payload [Hash] The incoming Slack shortcut payload
+        # @return [Boolean] true if this handler should process the shortcut
+        def matches?(payload)
+          return false unless matcher_config
+          return false unless SHORTCUT_TYPES.include?(payload['type'])
+
+          if matcher_config[:callback_id].is_a?(Regexp)
+            matcher_config[:callback_id].match?(payload['callback_id'])
+          else
+            payload['callback_id'] == matcher_config[:callback_id]
+          end
+        end
+      end
+
+      # Returns the callback_id from the shortcut payload
+      #
+      # @return [String, nil] The callback_id
+      def callback_id
+        payload['callback_id']
+      end
+
+      # Returns the trigger_id for opening modals
+      #
+      # Slack provides a trigger_id with shortcuts that can be used
+      # to open modals within 3 seconds of receiving the shortcut.
+      #
+      # @return [String, nil] The trigger_id for views.open
+      def trigger_id
+        payload['trigger_id']
+      end
+
+      # Returns the type of shortcut (:global or :message)
+      #
+      # @return [Symbol] :message for message shortcuts (message_action),
+      #   :global for global shortcuts
+      def shortcut_type
+        payload['type'] == 'message_action' ? :message : :global
+      end
+
+      # Returns the message object for message shortcuts
+      #
+      # Only available for message shortcuts (message_action type).
+      # Contains the original message that the shortcut was triggered on.
+      #
+      # @return [Hash, nil] The message object or nil for global shortcuts
+      def message
+        payload['message']
+      end
+
+      # Returns the text of the message for message shortcuts
+      #
+      # Convenience method to get the message text directly.
+      #
+      # @return [String, nil] The message text or nil if not available
+      def message_text
+        message&.dig('text')
+      end
+    end
+  end
+
+  # Top-level alias for convenience
+  ShortcutHandler = Handlers::ShortcutHandler
+end

data/lib/bolt_rb/handlers/view_submission_handler.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module BoltRb
+  module Handlers
+    # Handler for Slack view submissions (modal form submissions)
+    #
+    # This handler provides the `view` DSL for matching view_submission payloads.
+    # View submissions are triggered when users click the submit button on modals
+    # opened via views.open or views.push.
+    #
+    # @example Basic modal submission handler
+    #   class CreateTicketSubmitHandler < BoltRb::ViewSubmissionHandler
+    #     view 'create_ticket_modal'
+    #
+    #     def handle
+    #       ack
+    #       # Process the form submission
+    #       ticket_title = values.dig('title_block', 'title_input', 'value')
+    #     end
+    #   end
+    #
+    # @example Handler with validation errors
+    #   class ValidatedSubmitHandler < BoltRb::ViewSubmissionHandler
+    #     view 'validated_form'
+    #
+    #     def handle
+    #       if invalid_input?
+    #         ack(response_action: 'errors', errors: { 'input_block' => 'Invalid input' })
+    #       else
+    #         ack
+    #         process_submission
+    #       end
+    #     end
+    #   end
+    #
+    # @example Regex-based view matching
+    #   class DynamicFormHandler < BoltRb::ViewSubmissionHandler
+    #     view /^form_step_/
+    #
+    #     def handle
+    #       ack
+    #       step = callback_id.gsub('form_step_', '')
+    #       # Handle based on step
+    #     end
+    #   end
+    class ViewSubmissionHandler < Base
+      class << self
+        # Configures which callback_id this handler responds to
+        #
+        # @param callback_id [String, Regexp] The callback_id to match (exact string or regex)
+        # @return [void]
+        #
+        # @example Match exact callback_id
+        #   view 'create_ticket_modal'
+        #
+        # @example Match callback_id pattern
+        #   view /^create_/
+        def view(callback_id)
+          @matcher_config = {
+            type: :view_submission,
+            callback_id: callback_id
+          }
+        end
+
+        # Determines if this handler matches the given payload
+        #
+        # Checks if the payload is a view_submission type and if the
+        # callback_id matches the configured pattern.
+        #
+        # @param payload [Hash] The incoming Slack view_submission payload
+        # @return [Boolean] true if this handler should process the submission
+        def matches?(payload)
+          return false unless matcher_config
+          return false unless payload['type'] == 'view_submission'
+
+          view_callback_id = payload.dig('view', 'callback_id')
+          return false unless view_callback_id
+
+          if matcher_config[:callback_id].is_a?(Regexp)
+            matcher_config[:callback_id].match?(view_callback_id)
+          else
+            view_callback_id == matcher_config[:callback_id]
+          end
+        end
+      end
+
+      # Returns the view object from the payload
+      #
+      # @return [Hash, nil] The view object containing callback_id, private_metadata, state, etc.
+      def view
+        payload['view']
+      end
+
+      # Returns the callback_id from the view
+      #
+      # @return [String, nil] The callback_id
+      def callback_id
+        view&.dig('callback_id')
+      end
+
+      # Returns the private_metadata from the view
+      #
+      # Private metadata is a string field you can use to pass data between
+      # the view open and submission events. Often used to store IDs.
+      #
+      # @return [String, nil] The private_metadata value
+      def private_metadata
+        view&.dig('private_metadata')
+      end
+
+      # Returns the state values from the submitted form
+      #
+      # The values hash is keyed by block_id, then action_id, then contains
+      # the input value (format depends on input type).
+      #
+      # @return [Hash] The form values hash
+      # @example Structure
+      #   {
+      #     'title_block' => {
+      #       'title_input' => { 'type' => 'plain_text_input', 'value' => 'My Title' }
+      #     },
+      #     'select_block' => {
+      #       'select_input' => { 'type' => 'static_select', 'selected_option' => { 'value' => 'opt1' } }
+      #     }
+      #   }
+      def values
+        view&.dig('state', 'values') || {}
+      end
+
+      # Returns the user ID from the payload
+      #
+      # @return [String, nil] The user ID who submitted the form
+      def user_id
+        payload.dig('user', 'id')
+      end
+
+      # Returns the response URLs for block-based responses
+      #
+      # Only present if the modal was opened from a message interaction.
+      #
+      # @return [Array<Hash>] Array of response_url objects
+      def response_urls
+        payload['response_urls'] || []
+      end
+
+      # Returns the hash value of the submitted view
+      #
+      # Used for optimistic locking when updating views.
+      #
+      # @return [String, nil] The view hash
+      def view_hash
+        view&.dig('hash')
+      end
+    end
+  end
+
+  # Top-level alias for convenience
+  ViewSubmissionHandler = Handlers::ViewSubmissionHandler
+end

data/lib/bolt_rb/middleware/base.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module BoltRb
+  module Middleware
+    # Base class for all middleware
+    #
+    # Middleware classes should inherit from this and override #call
+    # to implement custom behavior. The default implementation simply
+    # yields to the next middleware in the chain.
+    #
+    # @example Custom middleware
+    #   class AuthMiddleware < BoltRb::Middleware::Base
+    #     def call(context)
+    #       if authorized?(context)
+    #         yield if block_given?
+    #       else
+    #         context.respond("Unauthorized")
+    #       end
+    #     end
+    #   end
+    class Base
+      # Processes the request through this middleware
+      #
+      # Override this method in subclasses to add custom behavior.
+      # Always call yield to continue the middleware chain.
+      #
+      # @param context [BoltRb::Context] The request context
+      # @yield Continues to the next middleware in the chain
+      # @return [void]
+      def call(context)
+        yield if block_given?
+      end
+    end
+  end
+end

data/lib/bolt_rb/middleware/chain.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module BoltRb
+  module Middleware
+    # Executes a chain of middleware in order
+    #
+    # The middleware chain follows the onion model where each middleware
+    # can execute code before and after the next middleware in the chain.
+    # This is similar to Rack middleware or Rails around_action filters.
+    #
+    # @example Basic usage
+    #   chain = Chain.new([LoggingMiddleware, AuthMiddleware])
+    #   chain.call(context) do
+    #     # Handler code runs after all middleware have yielded
+    #   end
+    class Chain
+      # Creates a new middleware chain
+      #
+      # @param middleware_classes [Array<Class>] Array of middleware classes to instantiate and run
+      def initialize(middleware_classes)
+        @middleware_classes = middleware_classes
+      end
+
+      # Executes the middleware chain
+      #
+      # Each middleware is instantiated and called in order. The provided
+      # block is called after all middleware have yielded. Middleware can
+      # stop the chain by not yielding.
+      #
+      # @param context [BoltRb::Context] The request context
+      # @yield The handler to run after middleware processing
+      # @return [void]
+      def call(context, &block)
+        chain = @middleware_classes.map(&:new)
+        run_chain(chain, context, &block)
+      end
+
+      private
+
+      # Recursively runs through the middleware chain
+      #
+      # @param chain [Array<Base>] Remaining middleware instances
+      # @param context [BoltRb::Context] The request context
+      # @yield The handler to run when chain is empty
+      # @return [void]
+      def run_chain(chain, context, &block)
+        if chain.empty?
+          block.call
+        else
+          middleware = chain.shift
+          middleware.call(context) do
+            run_chain(chain, context, &block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bolt_rb/middleware/logging.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module BoltRb
+  module Middleware
+    # Logging middleware for request/response logging
+    #
+    # Logs the event type being processed and the time taken to process it.
+    # This is useful for debugging and monitoring your Bolt application.
+    #
+    # @example Output
+    #   [BoltRb] Processing event:message
+    #   [BoltRb] Completed event:message in 12.34ms
+    class Logging < Base
+      # Processes the request with logging
+      #
+      # Logs the event type before processing and the elapsed time after.
+      #
+      # @param context [BoltRb::Context] The request context
+      # @yield Continues to the next middleware in the chain
+      # @return [void]
+      def call(context)
+        event_type = determine_event_type(context.payload)
+        BoltRb.logger.info "[BoltRb] Processing #{event_type}"
+        started = Time.now
+
+        yield if block_given?
+
+        elapsed = ((Time.now - started) * 1000).round(2)
+        BoltRb.logger.info "[BoltRb] Completed #{event_type} in #{elapsed}ms"
+      end
+
+      private
+
+      # Determines the event type from the payload
+      #
+      # Handles various payload formats from Slack:
+      # - Events API: event.type
+      # - Slash commands: command
+      # - Block actions: type with action_ids
+      # - Shortcuts: type with callback_id
+      #
+      # @param payload [Hash] The raw Slack payload
+      # @return [String] A descriptive event type string
+      def determine_event_type(payload)
+        if payload['event']
+          "event:#{payload['event']['type']}"
+        elsif payload['command']
+          "command:#{payload['command']}"
+        elsif payload['type'] == 'block_actions'
+          action_ids = payload['actions']&.map { |a| a['action_id'] }&.join(',')
+          "action:#{action_ids}"
+        elsif payload['type'] == 'shortcut' || payload['type'] == 'message_action'
+          "shortcut:#{payload['callback_id']}"
+        else
+          'unknown'
+        end
+      end
+    end
+  end
+end

data/lib/bolt_rb/router.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module BoltRb
+  # Router maintains a registry of handlers and routes incoming payloads
+  # to the appropriate handlers based on their matching criteria.
+  #
+  # The router acts as the central dispatch mechanism for Bolt applications,
+  # collecting registered handlers and determining which ones should process
+  # a given Slack payload.
+  #
+  # @example Basic usage
+  #   router = BoltRb::Router.new
+  #
+  #   router.register(MyMessageHandler)
+  #   router.register(MyCommandHandler)
+  #
+  #   handlers = router.route(payload)
+  #   handlers.each { |h| h.new(context).call }
+  #
+  # @example Using the global router
+  #   BoltRb.router.register(MyHandler)
+  #   BoltRb.router.route(payload)
+  class Router
+    # Creates a new Router instance with an empty handler registry
+    def initialize
+      @handlers = []
+    end
+
+    # Registers a handler class with the router
+    #
+    # The handler class should respond to .matches?(payload) to determine
+    # if it should process a given payload. Duplicate registrations are ignored.
+    #
+    # @param handler_class [Class] A handler class (EventHandler, CommandHandler, etc.)
+    # @return [void]
+    #
+    # @example
+    #   router.register(MyMessageHandler)
+    def register(handler_class)
+      @handlers << handler_class unless @handlers.include?(handler_class)
+    end
+
+    # Routes a payload to all matching handlers
+    #
+    # Iterates through all registered handlers and returns those whose
+    # .matches?(payload) method returns true.
+    #
+    # @param payload [Hash] The incoming Slack payload
+    # @return [Array<Class>] Array of handler classes that match the payload
+    #
+    # @example
+    #   payload = { 'event' => { 'type' => 'message', 'text' => 'hello' } }
+    #   handlers = router.route(payload)
+    #   # => [MessageHandler, HelloHandler]
+    def route(payload)
+      @handlers.select { |handler| handler.matches?(payload) }
+    end
+
+    # Returns the number of registered handlers
+    #
+    # @return [Integer] The count of registered handlers
+    def handler_count
+      @handlers.length
+    end
+
+    # Removes all registered handlers
+    #
+    # Useful for testing or reconfiguration scenarios.
+    #
+    # @return [void]
+    def clear
+      @handlers.clear
+    end
+  end
+end