bolt_rb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9935362013533090530a02a62c08ba8705541780b5d859bf0dcbd1ea84a1dbe2
+  data.tar.gz: 9de74bd3e31abe9fea99e980803e4c649c520da33e73638ad11db0ed87eb8fd9
+SHA512:
+  metadata.gz: 9df04458ee8addd0827a52cf7e00e69a96da0acf04e928343ce0b67a9d47f446896ac32d8bf83af692d19eac81599ba63e5e165411de9e931ad343ad4fd97fba
+  data.tar.gz: 52fb0f69a9eb711740c6194ce2a3d1125cf85ad76f942fd8f211bcd16daab3a8678af5f87c0350db5d9b3aae1ee85a5a98ca5580ae4ec550dc40c66091971c03

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jon Whitcraft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,218 @@
+# bolt-rb
+
+> **Note:** This project is provided as-is with no active support. I'll add features when I need them and accept PRs if someone wants to contribute fixes. Use at your own risk.
+
+A [bolt-js](https://slack.dev/bolt-js) inspired framework for building Slack bots in Ruby using Socket Mode.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'bolt_rb'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+```ruby
+require 'bolt_rb'
+
+BoltRb.configure do |config|
+  config.bot_token = ENV.fetch('SLACK_BOT_TOKEN')
+  config.app_token = ENV.fetch('SLACK_APP_TOKEN')
+  config.handler_paths = ['./handlers']
+end
+
+app = BoltRb::App.new
+
+# Graceful shutdown
+%w[INT TERM].each do |signal|
+  Signal.trap(signal) { app.request_stop }
+end
+
+app.start
+```
+
+## Configuration
+
+| Option | Description |
+|--------|-------------|
+| `bot_token` | Your Slack bot token (`xoxb-...`) |
+| `app_token` | Your Slack app-level token (`xapp-...`) for Socket Mode |
+| `handler_paths` | Array of directories to load handlers from |
+
+## Handlers
+
+Handlers are auto-registered when loaded. Just drop them in your handler paths.
+
+### Events
+
+Listen to Slack events like messages, reactions, app mentions:
+
+```ruby
+class GreetingHandler < BoltRb::EventHandler
+  listen_to :message, pattern: /hello/i
+
+  def handle
+    say "Hey there <@#{user}>!"
+  end
+end
+```
+
+```ruby
+class MentionHandler < BoltRb::EventHandler
+  listen_to :app_mention
+
+  def handle
+    say "You rang?"
+  end
+end
+```
+
+**Available methods:** `event`, `text`, `thread_ts`, `ts`, `user`, `channel`, `say`, `client`
+
+### Slash Commands
+
+Handle slash commands like `/deploy`:
+
+```ruby
+class DeployCommand < BoltRb::CommandHandler
+  command '/deploy'
+
+  def handle
+    ack "Deploying #{command_text}..."
+    # Do the work
+    say "Deployed #{command_text} successfully!"
+  end
+end
+```
+
+**Available methods:** `command_name`, `command_text`, `trigger_id`, `user`, `channel`, `ack`, `say`, `respond`, `client`
+
+### Actions
+
+Handle button clicks, select menus, and other interactive components:
+
+```ruby
+class ApproveHandler < BoltRb::ActionHandler
+  action 'approve_button'
+
+  def handle
+    ack
+    say "Approved by <@#{user}>!"
+  end
+end
+```
+
+Supports regex matching:
+
+```ruby
+class DynamicButtonHandler < BoltRb::ActionHandler
+  action /^approve_request_/
+
+  def handle
+    ack
+    request_id = action_id.gsub('approve_request_', '')
+    # Process the request
+  end
+end
+```
+
+**Available methods:** `action`, `action_id`, `action_value`, `block_id`, `trigger_id`, `user`, `channel`, `ack`, `say`, `respond`, `client`
+
+### Shortcuts
+
+Handle global shortcuts (lightning bolt menu) and message shortcuts:
+
+```ruby
+class CreateTicketHandler < BoltRb::ShortcutHandler
+  shortcut 'create_ticket'
+
+  def handle
+    ack
+    client.views_open(
+      trigger_id: trigger_id,
+      view: { type: 'modal', title: { type: 'plain_text', text: 'Create Ticket' }, ... }
+    )
+  end
+end
+```
+
+**Available methods:** `callback_id`, `trigger_id`, `shortcut_type`, `message`, `message_text`, `user`, `channel`, `ack`, `client`
+
+### View Submissions
+
+Handle modal form submissions:
+
+```ruby
+class TicketSubmitHandler < BoltRb::ViewSubmissionHandler
+  view 'create_ticket_modal'
+
+  def handle
+    title = values.dig('title_block', 'title_input', 'value')
+
+    if title.nil? || title.empty?
+      ack(response_action: 'errors', errors: { 'title_block' => 'Title is required' })
+    else
+      ack
+      say "Created ticket: #{title}"
+    end
+  end
+end
+```
+
+**Available methods:** `view`, `callback_id`, `private_metadata`, `values`, `view_hash`, `response_urls`, `user_id`, `ack`, `say`, `client`
+
+## Handler Methods
+
+All handlers have access to:
+
+| Method | Description |
+|--------|-------------|
+| `say(message)` | Post a message to the channel |
+| `ack(response)` | Acknowledge the event (required for commands, actions, shortcuts, views) |
+| `respond(message)` | Send a response using the response_url |
+| `client` | The `Slack::Web::Client` for API calls |
+| `payload` | The raw Slack payload |
+| `user` | The user ID who triggered the event |
+| `channel` | The channel ID |
+
+## Middleware
+
+Add handler-specific middleware:
+
+```ruby
+class ProtectedHandler < BoltRb::CommandHandler
+  command '/admin'
+  use AdminOnlyMiddleware
+
+  def handle
+    # Only admins get here
+  end
+end
+```
+
+## Slack App Setup
+
+1. Create a Slack app at [api.slack.com/apps](https://api.slack.com/apps)
+2. Enable **Socket Mode** under Settings
+3. Generate an **App-Level Token** with `connections:write` scope
+4. Add a **Bot Token** with the scopes you need (e.g., `chat:write`, `commands`)
+5. Install the app to your workspace
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## License
+
+MIT

data/lib/bolt_rb/app.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require 'slack-ruby-client'
+
+module BoltRb
+  # Main application class for running a Bolt app with Socket Mode
+  #
+  # This class initializes the Slack clients, loads handlers, and processes
+  # incoming events through the middleware chain and router.
+  #
+  # @example Basic usage
+  #   BoltRb.configure do |config|
+  #     config.bot_token = ENV['SLACK_BOT_TOKEN']
+  #     config.app_token = ENV['SLACK_APP_TOKEN']
+  #   end
+  #
+  #   app = BoltRb::App.new
+  #   app.start
+  #
+  # @example With custom handler paths
+  #   BoltRb.configure do |config|
+  #     config.bot_token = ENV['SLACK_BOT_TOKEN']
+  #     config.app_token = ENV['SLACK_APP_TOKEN']
+  #     config.handler_paths = ['lib/handlers']
+  #   end
+  #
+  #   app = BoltRb::App.new
+  #   app.start
+  class App
+    # @return [Slack::Web::Client] The Slack Web API client
+    attr_reader :client
+
+    # @return [Router] The router instance for dispatching events
+    attr_reader :router
+
+    # @return [Configuration] The configuration instance
+    attr_reader :config
+
+    # @return [SocketMode::Client] The Socket Mode client instance
+    attr_reader :socket_client
+
+    # Creates a new App instance
+    #
+    # Initializes the Slack Web API client for making API calls
+    # and the Socket Mode client for receiving events.
+    def initialize
+      @config = BoltRb.configuration
+      @router = BoltRb.router
+      @client = Slack::Web::Client.new(token: config.bot_token)
+
+      setup_socket_client
+    end
+
+    # Starts the Socket Mode connection
+    #
+    # Loads all handlers from configured paths and connects to Slack
+    # via Socket Mode to start receiving events.
+    #
+    # @return [void]
+    def start
+      load_handlers
+      BoltRb.logger.info '[BoltRb] Starting app...'
+      @socket_client.start
+    end
+
+    # Stops the Socket Mode connection
+    #
+    # Gracefully disconnects from Slack.
+    #
+    # @return [void]
+    def stop
+      BoltRb.logger.info '[BoltRb] Stopping app...'
+      @socket_client.stop
+    end
+
+    # Requests a stop - safe to call from trap context
+    #
+    # Use this in signal handlers instead of stop to avoid
+    # ThreadError from calling methods that use mutexes.
+    #
+    # @return [void]
+    def request_stop
+      @socket_client.request_stop
+    end
+
+    # @return [Boolean] Whether the app is currently running
+    def running?
+      @socket_client.running?
+    end
+
+    # Processes an incoming event payload
+    #
+    # Routes the event to matching handlers and executes them through
+    # the middleware chain. Errors in individual handlers are caught
+    # and passed to the configured error handler without stopping
+    # other handlers from executing.
+    #
+    # @param payload [Hash] The incoming Slack event payload
+    # @return [void]
+    def process_event(payload)
+      handlers = router.route(payload)
+      return if handlers.empty?
+
+      context = build_context(payload)
+
+      Middleware::Chain.new(config.middleware).call(context) do
+        handlers.each do |handler_class|
+          execute_handler(handler_class, context)
+        end
+      end
+    end
+
+    private
+
+    # Sets up the Socket Mode client with event handling
+    #
+    # @return [void]
+    def setup_socket_client
+      @socket_client = SocketMode::Client.new(
+        app_token: config.app_token,
+        logger: BoltRb.logger
+      )
+
+      @socket_client.on_message do |data|
+        handle_socket_event(data)
+      end
+    end
+
+    # Handles incoming Socket Mode events
+    #
+    # Extracts the payload from the Socket Mode envelope and routes it
+    # to the appropriate handlers.
+    #
+    # @param data [Hash] The Socket Mode envelope data
+    # @return [void]
+    def handle_socket_event(data)
+      payload = extract_payload(data)
+      process_event(payload) if payload
+    rescue StandardError => e
+      BoltRb.logger.error "[BoltRb] Error handling socket event: #{e.message}"
+      BoltRb.logger.error e.backtrace.first(5).join("\n")
+    end
+
+    # Extracts the event payload from a Socket Mode envelope
+    #
+    # @param data [Hash] The Socket Mode envelope
+    # @return [Hash, nil] The extracted payload or nil if not processable
+    def extract_payload(data)
+      case data['type']
+      when 'events_api'
+        data['payload']
+      when 'interactive', 'slash_commands', 'block_actions', 'view_submission', 'view_closed', 'shortcut'
+        data['payload']
+      else
+        # For unknown types, pass through the whole data
+        data
+      end
+    end
+
+    # Loads all handler files from configured paths
+    #
+    # @return [void]
+    def load_handlers
+      config.handler_paths.each do |path|
+        pattern = File.join(path, '**', '*.rb')
+        Dir.glob(pattern).sort.each do |file|
+          require file
+        end
+      end
+
+      BoltRb.logger.info "[BoltRb] Loaded #{router.handler_count} handlers"
+    end
+
+    # Builds a Context object for the given payload
+    #
+    # @param payload [Hash] The event payload
+    # @return [Context] The context for handler execution
+    def build_context(payload)
+      Context.new(
+        payload: payload,
+        client: client,
+        ack: build_ack_fn(payload)
+      )
+    end
+
+    # Builds the acknowledgement function for a payload
+    #
+    # Socket Mode acknowledgements are handled automatically by the
+    # SocketMode::Client, so this returns a no-op for handlers.
+    #
+    # @param _payload [Hash] The event payload (unused)
+    # @return [Proc] The ack function
+    def build_ack_fn(_payload)
+      # Socket Mode acks are handled automatically by the client
+      # This allows handlers to call ack() without errors
+      ->(_response = nil) {}
+    end
+
+    # Executes a single handler with error handling
+    #
+    # If the handler raises an exception, logs the error and calls
+    # the configured error handler. Does not re-raise, allowing
+    # other handlers to continue processing.
+    #
+    # @param handler_class [Class] The handler class to execute
+    # @param context [Context] The context for handler execution
+    # @return [void]
+    def execute_handler(handler_class, context)
+      handler_class.new(context).call
+    rescue StandardError => e
+      BoltRb.logger.error "[BoltRb] Error in #{handler_class}: #{e.message}"
+      BoltRb.logger.error e.backtrace.first(5).join("\n")
+      config.error_handler&.call(e, context.payload)
+    end
+  end
+end

data/lib/bolt_rb/configuration.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module BoltRb
+  # Configuration class for BoltRb applications
+  #
+  # Holds all settings including tokens, handler paths, logger,
+  # middleware stack, and error handling configuration.
+  #
+  # @example Basic configuration
+  #   BoltRb.configure do |config|
+  #     config.bot_token = ENV['SLACK_BOT_TOKEN']
+  #     config.app_token = ENV['SLACK_APP_TOKEN']
+  #     config.signing_secret = ENV['SLACK_SIGNING_SECRET']
+  #   end
+  #
+  # @example Adding custom middleware
+  #   BoltRb.configure do |config|
+  #     config.use MyCustomMiddleware
+  #   end
+  #
+  class Configuration
+    attr_accessor :bot_token, :app_token, :signing_secret,
+                  :handler_paths, :logger, :error_handler
+
+    attr_reader :middleware
+
+    def initialize
+      @handler_paths = ['app/slack_handlers']
+      @logger = Logger.new($stdout)
+      @logger.level = Logger::INFO
+      @middleware = [BoltRb::Middleware::Logging]
+    end
+
+    # Add middleware to the stack
+    #
+    # @param middleware_class [Class] The middleware class to add
+    # @return [Array<Class>] The updated middleware stack
+    def use(middleware_class)
+      @middleware << middleware_class
+    end
+  end
+end

data/lib/bolt_rb/context.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+
+module BoltRb
+  # Context wraps the incoming Slack event payload and provides
+  # convenience methods for responding to events.
+  #
+  # This is the object passed to event handlers and provides access to:
+  # - The raw payload data
+  # - The Slack Web API client
+  # - Helper methods like say(), ack(), and respond()
+  #
+  # @example Basic usage in an event handler
+  #   app.event('message') do |ctx|
+  #     ctx.say("You said: #{ctx.text}")
+  #   end
+  #
+  # @example Using respond for slash commands
+  #   app.command('/echo') do |ctx|
+  #     ctx.ack
+  #     ctx.respond("Echoing: #{ctx.text}")
+  #   end
+  class Context
+    # @return [Hash] The raw payload from the Slack event
+    attr_reader :payload
+
+    # @return [Slack::Web::Client] The Slack Web API client
+    attr_reader :client
+
+    # Creates a new Context instance
+    #
+    # @param payload [Hash] The raw event payload from Slack
+    # @param client [Slack::Web::Client] The Slack Web API client
+    # @param ack [Proc] The acknowledgement function to call
+    def initialize(payload:, client:, ack:)
+      @payload = payload
+      @client = client
+      @ack_fn = ack
+      @acked = false
+    end
+
+    # Returns the event portion of the payload
+    #
+    # @return [Hash, nil] The event data or nil if not present
+    def event
+      payload['event']
+    end
+
+    # Extracts the user ID from the payload
+    #
+    # Handles various payload formats:
+    # - event.user (string)
+    # - user_id (slash commands)
+    # - user (string)
+    # - user.id (nested object)
+    #
+    # @return [String, nil] The user ID or nil if not found
+    def user
+      extract_id(
+        payload.dig('event', 'user') ||
+        payload['user_id'] ||
+        payload['user'] ||
+        payload.dig('user', 'id')
+      )
+    end
+
+    # Extracts the channel ID from the payload
+    #
+    # Handles various payload formats:
+    # - event.channel (string)
+    # - channel_id (slash commands)
+    # - channel (string)
+    # - channel.id (nested object)
+    #
+    # @return [String, nil] The channel ID or nil if not found
+    def channel
+      extract_id(
+        payload.dig('event', 'channel') ||
+        payload['channel_id'] ||
+        payload['channel'] ||
+        payload.dig('channel', 'id')
+      )
+    end
+
+    # Extracts the text content from the event
+    #
+    # @return [String, nil] The message text or nil if not present
+    def text
+      event&.dig('text')
+    end
+
+    # Acknowledges the event
+    #
+    # For events that require acknowledgement (slash commands, interactive
+    # components), this method sends the acknowledgement to Slack.
+    #
+    # @param response [String, Hash, nil] Optional response to include with the ack
+    # @return [void]
+    def ack(response = nil)
+      @ack_fn.call(response)
+      @acked = true
+    end
+
+    # Returns whether this context has been acknowledged
+    #
+    # @return [Boolean] true if ack() has been called
+    def acked?
+      @acked
+    end
+
+    # Posts a message to the channel
+    #
+    # @param message [String, Hash] The message to post. Can be a simple string
+    #   or a hash with chat.postMessage options
+    # @return [Hash] The response from the Slack API
+    #
+    # @example Simple text message
+    #   ctx.say("Hello!")
+    #
+    # @example Message with options
+    #   ctx.say(text: "Hello!", thread_ts: "123.456")
+    def say(message)
+      options = message.is_a?(Hash) ? message : { text: message }
+      client.chat_postMessage(options.merge(channel: channel))
+    end
+
+    # Responds using the response_url
+    #
+    # This is used for slash commands and interactive components where
+    # Slack provides a response_url for sending follow-up messages.
+    #
+    # @param message [String, Hash] The message to send. Can be a simple string
+    #   or a hash with response options (text, blocks, response_type, etc.)
+    # @return [Net::HTTPResponse, nil] The HTTP response or nil if no response_url
+    #
+    # @example Simple response
+    #   ctx.respond("Processing complete!")
+    #
+    # @example Ephemeral response with blocks
+    #   ctx.respond(
+    #     text: "Here's your data",
+    #     response_type: "ephemeral",
+    #     blocks: [...]
+    #   )
+    def respond(message)
+      response_url = payload['response_url']
+      return unless response_url
+
+      options = message.is_a?(Hash) ? message : { text: message }
+      uri = URI(response_url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      request = Net::HTTP::Post.new(uri.path)
+      request['Content-Type'] = 'application/json'
+      request.body = options.to_json
+      http.request(request)
+    end
+
+    private
+
+    # Extracts an ID from a value that might be a string or hash
+    #
+    # @param value [String, Hash, nil] The value to extract from
+    # @return [String, nil] The extracted ID
+    def extract_id(value)
+      return nil if value.nil?
+
+      value.is_a?(Hash) ? value['id'] : value
+    end
+  end
+end