chat_sdk 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36c07ba6e29c7d1cf858767caca271826418d829547426f1677a32c94133205e
-  data.tar.gz: 0a00e35abebb7f43b8c9bb68576fce634d46088430029b33ad7f63c2d3820bbb
+  metadata.gz: 729c1baa552d9bad38924b1f026c75c769bb26b6dc3b4784e5e900ca66c93d21
+  data.tar.gz: 677e7b87d6177385e6a0b3fbe52da890a3238c31dd36c754c62d09e224ba385c
 SHA512:
-  metadata.gz: 5483b777f81c28e3e367f84d0e4a3413b8f7d60ff09036d6148a3e565a5287252660e0fcc2aa3e7cce6c0d2f607f7a4834514f7f4da66445c1a6728ebc1a0ff6
-  data.tar.gz: b2650d632171a42556aab7d6df09d5b6c79e7cfd1a032b9806a5d49b65892c3c62435d22463a24d382904df03c02b81eb3e93d5f86b0b83570e5ff24f9bb88a8
+  metadata.gz: 50cb4ab19ee8b817e4395030a9ca15ddd8980d785d0bff8f0dabb13462b636259fd6ff42afca5c2cfece542e74dd50224188dd2090e3bbf3378e558045cb4bf3
+  data.tar.gz: 13183055e0ce37f542350374d6210f8ec6dd2b63c34a0acef2629515cf0009bbcc7e93d03c64b39b96d16982dbce8f0904c1a7a51f1661f267f9880bf59d56bc

data/lib/chat_sdk/adapter/base.rb

@@ -22,6 +22,10 @@ module ChatSDK
         nil
       end
 
+      def webhook_response(_events, _request = nil)
+        nil
+      end
+
       def parse_events(rack_request)
         raise NotImplementedError
       end
@@ -31,6 +35,12 @@ module ChatSDK
         raise NotImplementedError
       end
 
+      # Stream using a platform-native API, or return nil before consuming
+      # chunks to delegate to the core post+edit fallback.
+      def stream(channel_id:, thread_id:, stream:, options: {})
+        nil
+      end
+
       def reply_message(channel_id:, message_id:, message:, thread_id: nil)
         require_capability!(:replies)
         raise NotImplementedError
@@ -41,12 +51,12 @@ module ChatSDK
         raise NotImplementedError
       end
 
-      def edit_message(channel_id:, message_id:, message:)
+      def edit_message(channel_id:, message_id:, message:, thread_id: nil)
         require_capability!(:edit_messages)
         raise NotImplementedError
       end
 
-      def delete_message(channel_id:, message_id:)
+      def delete_message(channel_id:, message_id:, thread_id: nil)
         require_capability!(:delete_messages)
         raise NotImplementedError
       end
@@ -61,12 +71,12 @@ module ChatSDK
         raise NotImplementedError
       end
 
-      def add_reaction(channel_id:, message_id:, emoji:)
+      def add_reaction(channel_id:, message_id:, emoji:, thread_id: nil)
         require_capability!(:reactions)
         raise NotImplementedError
       end
 
-      def remove_reaction(channel_id:, message_id:, emoji:)
+      def remove_reaction(channel_id:, message_id:, emoji:, thread_id: nil)
         require_capability!(:reactions)
         raise NotImplementedError
       end
@@ -96,11 +106,15 @@ module ChatSDK
         raise NotImplementedError
       end
 
-      def start_typing(channel_id:, thread_id: nil)
+      def start_typing(channel_id:, thread_id: nil, message_id: nil)
         require_capability!(:typing_indicator)
         raise NotImplementedError
       end
 
+      def concurrency_scope(_event)
+        nil
+      end
+
       def mention(user_id)
         raise NotImplementedError
       end

data/lib/chat_sdk/adapter/invocation.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Adapter
+    module Invocation
+      private
+
+      def call_adapter(method_name, **kwargs)
+        params = adapter.method(method_name).parameters
+        accepts_thread_id = params.any? do |type, name|
+          type == :keyrest || (%i[key keyreq].include?(type) && name == :thread_id)
+        end
+        kwargs.delete(:thread_id) unless accepts_thread_id
+        adapter.public_send(method_name, **kwargs)
+      end
+    end
+  end
+end

data/lib/chat_sdk/ai/conversation_scope.rb

@@ -4,29 +4,39 @@ module ChatSDK
   module AI
     module ConversationScope
       THREAD_KEY = :chat_sdk_ai_conversation_scope
+      ACTIVE_KEY = :chat_sdk_ai_conversation_scope_active
 
       class << self
         def current
           ::Thread.current[THREAD_KEY]
         end
 
+        def active?
+          !!::Thread.current[ACTIVE_KEY]
+        end
+
         def with(thread)
           previous = current
+          previous_active = active?
           ::Thread.current[THREAD_KEY] = scope_for(thread)
+          ::Thread.current[ACTIVE_KEY] = true
           yield
         ensure
           ::Thread.current[THREAD_KEY] = previous
+          ::Thread.current[ACTIVE_KEY] = previous_active
         end
 
         def scope_for(value)
           return if value.nil?
           return value.transform_keys(&:to_sym) if value.is_a?(Hash)
 
-          {
+          scope = {
             adapter_name: value.adapter.name.to_sym,
             channel_id: value.respond_to?(:channel_id) ? value.channel_id.to_s : value.id.to_s,
             thread_id: value.is_a?(ChatSDK::Thread) ? value.id.to_s : nil
           }
+          scope[:message_id] = value.current_message.id if value.respond_to?(:current_message) && value.current_message
+          scope
         end
       end
     end

data/lib/chat_sdk/ai/stream_handler.rb

@@ -3,9 +3,9 @@
 module ChatSDK
   module AI
     class StreamHandler
-      def self.stream_to_thread(thread, enumerable, placeholder: "Thinking...")
-        thread.post_stream(placeholder: placeholder) do |stream|
-          enumerable.each { |chunk| stream << chunk.to_s }
+      def self.stream_to_thread(thread, enumerable, placeholder: "Thinking...", **plan_options)
+        thread.post_stream(placeholder: placeholder, **plan_options) do |stream|
+          enumerable.each { |chunk| stream << chunk }
         end
       end
     end

data/lib/chat_sdk/ai/tool_builder.rb

@@ -131,7 +131,8 @@ module ChatSDK
             properties: {
               adapter_name: {type: "string", description: "Adapter name"},
               channel_id: {type: "string", description: "Channel ID"},
-              thread_id: {type: "string", description: "Thread ID (optional)"}
+              thread_id: {type: "string", description: "Thread ID (optional)"},
+              message_id: {type: "string", description: "Current message ID (optional)"}
             },
             required: %w[adapter_name channel_id]
           },

data/lib/chat_sdk/ai/tool_executor.rb

@@ -5,13 +5,11 @@ module ChatSDK
     class ToolExecutor
       def initialize(chat:, scope: nil, strict_scope: false)
         @chat = chat
-        @scope = if scope == false
-          false
-        else
-          ConversationScope.scope_for(scope) || ConversationScope.current&.dup
-        end
+        @scope = (scope == false) ? false : (ConversationScope.scope_for(scope) || ConversationScope.current&.dup)
+        @created_in_handler = ConversationScope.active?
+        validate_scope!(@scope) if @scope
         @strict_scope = strict_scope
-        @warned_unscoped = false
+        @warned_unscoped = {}
       end
 
       def execute(tool_name, arguments)
@@ -20,7 +18,7 @@ module ChatSDK
 
         args = arguments.transform_keys(&:to_sym)
         adapter_name = args[:adapter_name].to_sym
-        guard_scope!(adapter_name, args) unless tool_name == :send_direct_message
+        guard_scope!(tool_name, adapter_name, args)
 
         send(:"execute_#{tool_name}", adapter_name, args)
       end
@@ -48,24 +46,25 @@ module ChatSDK
 
       def execute_post_message(adapter_name, args)
         channel = @chat.channel(args[:channel_id], adapter_name: adapter_name)
+        message = ChatSDK::PostableMessage.new(text: args[:text], ai_generated: true)
         if args[:thread_id]
           thread = channel.thread(args[:thread_id])
-          result = thread.post(args[:text])
+          result = thread.post(message)
         else
-          result = channel.post(args[:text])
+          result = channel.post(message)
         end
         {id: result.id, text: args[:text]}
       end
 
       def execute_send_direct_message(adapter_name, args)
         dm_channel = @chat.open_dm(args[:user_id], adapter_name: adapter_name)
-        result = dm_channel.post(args[:text])
+        result = dm_channel.post(ChatSDK::PostableMessage.new(text: args[:text], ai_generated: true))
         {id: result.id, channel_id: dm_channel.id}
       end
 
       def execute_edit_message(adapter_name, args)
         thread = target_thread(adapter_name, args)
-        thread.edit(args[:message_id], args[:text])
+        thread.edit(args[:message_id], ChatSDK::PostableMessage.new(text: args[:text], ai_generated: true))
         {success: true}
       end
 
@@ -89,7 +88,9 @@ module ChatSDK
 
       def execute_start_typing(adapter_name, args)
         adapter = @chat.adapter(adapter_name)
-        adapter.start_typing(channel_id: args[:channel_id], thread_id: args[:thread_id])
+        scoped_message_id = @scope.is_a?(Hash) ? @scope[:message_id] : nil
+        message_id = args[:message_id] || ConversationScope.current&.[](:message_id) || scoped_message_id
+        adapter.start_typing(channel_id: args[:channel_id], thread_id: args[:thread_id], message_id: message_id)
         {success: true}
       end
 
@@ -102,18 +103,25 @@ module ChatSDK
         channel.thread(args[:thread_id] || args[:channel_id])
       end
 
-      def guard_scope!(adapter_name, args)
+      def guard_scope!(tool_name, adapter_name, args)
         return if @scope == false
 
         scope = @scope || ConversationScope.current
         unless scope
-          unless @warned_unscoped
+          if ConversationScope.active? || @created_in_handler
+            raise ChatSDK::Error, "AI tool call requires an explicit scope when run inside a handler without a conversation"
+          end
+
+          unless @warned_unscoped[tool_name]
             ChatSDK::Log.warn("AI tool ran without a conversation scope; pass scope: to create_executor to confine access")
-            @warned_unscoped = true
+            @warned_unscoped[tool_name] = true
           end
+
           return
         end
 
+        return if tool_name == :send_direct_message
+
         target_channel = args[:channel_id].to_s
         target_thread = args[:thread_id]&.to_s
         same_channel = adapter_name == scope.fetch(:adapter_name).to_sym && target_channel == scope.fetch(:channel_id).to_s
@@ -125,6 +133,15 @@ module ChatSDK
         active = [scope[:adapter_name], scope[:channel_id], scope[:thread_id]].compact.join(":")
         raise ChatSDK::Error, "AI tool call blocked: executor is scoped to #{active.inspect}, but targeted #{target.inspect}"
       end
+
+      def validate_scope!(scope)
+        %i[channel_id thread_id].each do |key|
+          next if key == :thread_id && scope[key].nil?
+          next unless scope.key?(key) && scope[key].to_s.empty?
+
+          raise ChatSDK::ConfigurationError, "AI tool scope #{key} must not be empty"
+        end
+      end
     end
   end
 end

data/lib/chat_sdk/author.rb

@@ -4,11 +4,12 @@ module ChatSDK
   class Author
     attr_reader :id, :name, :platform, :locale, :email, :raw
 
-    def initialize(id:, name:, platform:, bot: false, system: false, locale: nil, email: nil, raw: nil)
+    def initialize(id:, name:, platform:, bot: false, me: false, system: false, locale: nil, email: nil, raw: nil)
       @id = id
       @name = name
       @platform = platform
       @bot = bot
+      @me = !!me
       @system = system
       @locale = locale
       @email = email
@@ -19,6 +20,10 @@ module ChatSDK
       @bot
     end
 
+    def me?
+      @me
+    end
+
     def system?
       @system
     end

data/lib/chat_sdk/cards/actions_context.rb

@@ -9,28 +9,50 @@ module ChatSDK
         @nodes = []
       end
 
-      def button(text, id:, style: nil, value: nil, tooltip: nil)
+      def button(text, id:, style: nil, value: nil, tooltip: nil, visible_to: nil, disabled: nil)
         attrs = {text: text, id: id}
         attrs[:style] = style if style
         attrs[:value] = value if value
         attrs[:tooltip] = tooltip if tooltip
+        attrs[:visible_to] = visible_to if visible_to
+        attrs[:disabled] = disabled unless disabled.nil?
         @nodes << Node.new(:button, attributes: attrs)
       end
 
-      def link_button(text, url:, id: nil, tooltip: nil)
+      def link_button(text, url:, id: nil, style: nil, tooltip: nil, visible_to: nil)
         attrs = {text: text, url: url}
         attrs[:id] = id if id
+        attrs[:style] = style if style
         attrs[:tooltip] = tooltip if tooltip
+        attrs[:visible_to] = visible_to if visible_to
         @nodes << Node.new(:link_button, attributes: attrs)
       end
 
-      def select(id:, placeholder: nil, &block)
+      def select(id:, placeholder: nil, label: nil, initial_option: nil, optional: nil, dispatch_action: nil, &block)
         ctx = SelectContext.new
-        ctx.instance_eval(&block)
+        ctx.instance_eval(&block) if block
+        raise ArgumentError, "Select requires at least one option" if ctx.nodes.empty?
+
         attrs = {id: id}
         attrs[:placeholder] = placeholder if placeholder
+        attrs[:label] = label unless label.nil?
+        attrs[:initial_option] = initial_option unless initial_option.nil?
+        attrs[:optional] = optional unless optional.nil?
+        attrs[:dispatch_action] = dispatch_action unless dispatch_action.nil?
         @nodes << Node.new(:select, attributes: attrs, children: ctx.nodes)
       end
+
+      def radio_select(id:, label:, initial_option: nil, optional: nil, dispatch_action: nil, &block)
+        ctx = SelectContext.new
+        ctx.instance_eval(&block) if block
+        raise ArgumentError, "RadioSelect requires at least one option" if ctx.nodes.empty?
+
+        attrs = {id: id, label: label}
+        attrs[:initial_option] = initial_option unless initial_option.nil?
+        attrs[:optional] = optional unless optional.nil?
+        attrs[:dispatch_action] = dispatch_action unless dispatch_action.nil?
+        @nodes << Node.new(:radio_select, attributes: attrs, children: ctx.nodes)
+      end
     end
   end
 end

data/lib/chat_sdk/cards/builder.rb

@@ -3,10 +3,13 @@
 module ChatSDK
   module Cards
     class Builder
-      def initialize(title: nil, subtitle: nil, width: nil, &block)
+      RESERVED_TEXT_INPUT_IDS = %w[actionId value msteams].freeze
+
+      def initialize(title: nil, subtitle: nil, width: nil, image_url: nil, &block)
         @title = title
         @subtitle = subtitle
         @width = width
+        @image_url = image_url
         @children = []
         instance_eval(&block) if block
       end
@@ -16,11 +19,18 @@ module ChatSDK
         attrs[:title] = @title if @title
         attrs[:subtitle] = @subtitle if @subtitle
         attrs[:width] = @width if @width
+        attrs[:image_url] = @image_url if @image_url
         Node.new(:card, attributes: attrs, children: @children)
       end
 
-      def text(content)
-        @children << Node.new(:text, attributes: {content: content})
+      def text(content, style: nil)
+        attrs = {content: content}
+        attrs[:style] = style unless style.nil?
+        @children << Node.new(:text, attributes: attrs)
+      end
+
+      def link(url:, label:)
+        @children << Node.new(:link, attributes: {url: url, label: label})
       end
 
       def divider
@@ -31,6 +41,18 @@ module ChatSDK
         @children << Node.new(:image, attributes: {url: url, alt: alt})
       end
 
+      def text_input(id:, label:, placeholder: nil, multiline: false, optional: false, value: nil, max_length: nil)
+        if RESERVED_TEXT_INPUT_IDS.include?(id.to_s)
+          raise ArgumentError, "Text input id #{id.inspect} is reserved"
+        end
+
+        attrs = {id: id, label: label, multiline: multiline, optional: optional}
+        attrs[:placeholder] = placeholder if placeholder
+        attrs[:value] = value unless value.nil?
+        attrs[:max_length] = max_length unless max_length.nil?
+        @children << Node.new(:text_input, attributes: attrs)
+      end
+
       def fields(&block)
         ctx = FieldsContext.new
         ctx.instance_eval(&block)
@@ -50,11 +72,15 @@ module ChatSDK
         @children << Node.new(:actions, children: ctx.nodes)
       end
 
-      def table(headers:, rows:, align: nil, caption: nil, page_size: nil)
+      def table(headers:, rows:, align: nil, caption: nil, page_size: nil, widths: nil, grid_lines: nil, grid_style: nil, vertical_align: nil)
         attrs = {headers: headers, rows: rows}
         attrs[:align] = align if align
         attrs[:caption] = caption if caption
         attrs[:page_size] = page_size if page_size
+        attrs[:widths] = widths if widths
+        attrs[:grid_lines] = grid_lines unless grid_lines.nil?
+        attrs[:grid_style] = grid_style if grid_style
+        attrs[:vertical_align] = vertical_align if vertical_align
         @children << Node.new(:table, attributes: attrs)
       end
 

data/lib/chat_sdk/cards/node.rb

@@ -27,10 +27,14 @@ module ChatSDK
           case node.type
           when :text
             [node.attributes[:content]]
+          when :link
+            ["#{node.attributes[:label]} (#{node.attributes[:url]})"]
           when :field
             ["#{node.attributes[:label]}: #{node.attributes[:value]}"]
           when :button, :link_button
             [node.attributes[:text]]
+          when :text_input
+            [node.attributes[:label]]
           when :table
             table_text(node)
           when :chart

data/lib/chat_sdk/cards/renderer.rb

@@ -9,13 +9,16 @@ module ChatSDK
         when :text then node.attributes[:content]
         when :divider then "---"
         when :image then "![#{node.attributes[:alt]}](#{node.attributes[:url]})"
+        when :link then "[#{node.attributes[:label]}](#{node.attributes[:url]})"
         when :fields then render_fields(node)
         when :field then "**#{node.attributes[:label]}**: #{node.attributes[:value]}"
         when :section then render_section(node)
         when :actions then render_actions(node)
         when :button then "[#{node.attributes[:text]}]"
         when :link_button then "[#{node.attributes[:text]}](#{node.attributes[:url]})"
+        when :text_input then node.attributes[:label]
         when :select then "_#{node.attributes[:placeholder] || "Select"}_"
+        when :radio_select then "_#{node.attributes[:label] || "Select"}_"
         when :table then render_table(node)
         when :chart then render_chart(node)
         else ""

data/lib/chat_sdk/chat.rb

@@ -3,17 +3,27 @@
 module ChatSDK
   class Chat
     attr_reader :config, :state, :history
+    # @api private
+    attr_reader :error_reporter
 
     def initialize(user_name:, adapters:, state:, **options)
       @config = Config.new(user_name: user_name, adapters: adapters, state: state, **options)
       @state = state
+      ChatSDK::Log.logger = @config.logger if @config.logger
+      ChatSDK::Log.level = @config.log_level if @config.log_level
       @adapters = adapters
+      @adapters.each_value { |adapter| adapter.set_state(state) if adapter.respond_to?(:set_state) }
       @registry = EventRegistry.new
       @history = History.new(self)
       @webhooks = {}
-      @dispatcher = Dispatcher.new(chat: self, config: @config, state: @state, registry: @registry)
-
-      ChatSDK::Log.level = @config.log_level
+      @error_reporter = ErrorReporter.new(@config.on_error)
+      @dispatcher = Dispatcher.new(
+        chat: self,
+        config: @config,
+        state: @state,
+        registry: @registry,
+        error_reporter: @error_reporter
+      )
     end
 
     # Event registration
@@ -26,7 +36,12 @@ module ChatSDK
     end
 
     def on_new_message(pattern = nil, &block)
-      @registry.register(:mention, matcher: pattern, &block)
+      unless pattern.nil? || pattern.is_a?(Regexp)
+        raise ChatSDK::ConfigurationError, "on_new_message pattern must be a Regexp or nil"
+      end
+      raise ChatSDK::ConfigurationError, "on_new_message requires a block" unless block
+
+      @registry.register(:new_message, matcher: pattern, &block)
     end
 
     def on_direct_message(&block)
@@ -53,6 +68,30 @@ module ChatSDK
       @registry.register(:slash_command, matcher: command, &block)
     end
 
+    def on_installed(&block)
+      @registry.register(:installed, &block)
+    end
+
+    def on_uninstalled(&block)
+      @registry.register(:uninstalled, &block)
+    end
+
+    def on_assistant_thread_started(&block)
+      @registry.register(:assistant_thread_started, &block)
+    end
+
+    def on_assistant_context_changed(&block)
+      @registry.register(:assistant_context_changed, &block)
+    end
+
+    def on_app_home_opened(&block)
+      @registry.register(:app_home_opened, &block)
+    end
+
+    def on_member_joined_channel(&block)
+      @registry.register(:member_joined_channel, &block)
+    end
+
     # Adapter access
     def adapter(name)
       @adapters.fetch(name) { raise ChatSDK::ConfigurationError, "Unknown adapter: #{name}" }
@@ -83,7 +122,28 @@ module ChatSDK
     # Event dispatch (called by webhook endpoints)
     def dispatch(event, adapter_name:)
       adp = adapter(adapter_name)
-      @dispatcher.dispatch(event, adapter: adp, adapter_name: adapter_name)
+      executor = @config.handler_executor
+      return @dispatcher.dispatch(event, adapter: adp, adapter_name: adapter_name) if executor == :inline
+
+      if executor == :thread
+        ::Thread.new { run_background_dispatch(event, adp, adapter_name) }
+      else
+        payload = {"adapter_name" => adapter_name.to_s, "event" => EventSerializer.dump(event)}
+        begin
+          executor.call(payload)
+        rescue => e
+          raise HandlerExecutorError, "handler_executor failed for #{event.type}: #{e.class}: #{e.message}"
+        end
+      end
+      nil
+    end
+
+    # Runs a payload produced for a callable handler_executor, such as from a background job.
+    def dispatch_serialized(payload)
+      payload = payload.transform_keys(&:to_s)
+      adapter_name = payload.fetch("adapter_name").to_sym
+      event = EventSerializer.load(payload.fetch("event"))
+      @dispatcher.dispatch(event, adapter: adapter(adapter_name), adapter_name: adapter_name)
     end
 
     # Deprecated compatibility alias for Vercel Chat SDK's former API.
@@ -92,6 +152,21 @@ module ChatSDK
     end
 
     private
+
+    def run_background_dispatch(event, adp, adapter_name)
+      @dispatcher.dispatch(event, adapter: adp, adapter_name: adapter_name)
+    rescue => e
+      # Nothing above this background thread can rescue errors raised during dispatch.
+      @error_reporter.report(
+        e,
+        "Background dispatch error (#{event.type})",
+        source: :dispatch,
+        adapter: adapter_name,
+        event_type: event.type,
+        thread_id: event.respond_to?(:thread_id) ? event.thread_id : nil,
+        channel_id: event.respond_to?(:channel_id) ? event.channel_id : nil
+      )
+    end
   end
 
   class WebhookAccessor

data/lib/chat_sdk/config.rb

@@ -15,7 +15,7 @@ module ChatSDK
 
     attr_reader :user_name, :adapters, :state, :on_lock_conflict,
       :dedupe_ttl, :streaming_update_interval, :handler_executor, :log_level,
-      :history_user, :concurrency
+      :history_user, :concurrency, :logger, :on_error
 
     def initialize(user_name:, adapters:, state:, **options)
       raise ConfigurationError, "user_name is required" if user_name.nil? || user_name.empty?
@@ -26,6 +26,8 @@ module ChatSDK
       @adapters = adapters
       @state = state
       merged = DEFAULTS.merge(options)
+      @logger = merged[:logger]
+      @on_error = merged[:on_error]
       @on_lock_conflict = merged[:on_lock_conflict]
       @concurrency = normalize_concurrency(merged[:concurrency], lock_scope: merged[:lock_scope])
       @dedupe_ttl = merged[:dedupe_ttl]
@@ -38,13 +40,43 @@ module ChatSDK
         retention: user_history.fetch(:retention, user_history.fetch("retention", 30 * 24 * 3600)),
         max_per_user: user_history.fetch(:max_per_user, user_history.fetch("max_per_user", 200))
       }
-      @log_level = merged[:log_level]
+      @log_level = if !@logger.nil? && !options.key?(:log_level)
+        nil
+      else
+        merged[:log_level]
+      end
 
+      validate_handler_executor!
+      validate_logger!
+      validate_on_error!
       validate_lock_conflict!
     end
 
     private
 
+    def validate_handler_executor!
+      return if %i[inline thread].include?(@handler_executor) || @handler_executor.respond_to?(:call)
+
+      raise ConfigurationError, "handler_executor must be :inline, :thread, or a callable"
+    end
+
+    def validate_logger!
+      return if @logger.nil?
+      unless %i[debug info warn error].all? { |level| @logger.respond_to?(level) }
+        raise ConfigurationError, "logger must respond to debug, info, warn, and error"
+      end
+
+      if !@log_level.nil? && !@logger.respond_to?(:level=)
+        raise ConfigurationError, "logger must respond to level= when log_level is set"
+      end
+    end
+
+    def validate_on_error!
+      return if @on_error.nil? || @on_error.respond_to?(:call)
+
+      raise ConfigurationError, "on_error must be a callable"
+    end
+
     def validate_lock_conflict!
       return if %i[drop force].include?(@on_lock_conflict) || @on_lock_conflict.respond_to?(:call)
       raise ConfigurationError, "on_lock_conflict must be :drop, :force, or a callable"