chat_sdk 1.1.0 → 1.3.0

data/lib/chat_sdk/dispatcher.rb

@@ -5,17 +5,25 @@ require "time"
 
 module ChatSDK
   class Dispatcher
+    LIFECYCLE_EVENT_TYPES = %i[
+      assistant_thread_started
+      assistant_context_changed
+      app_home_opened
+      member_joined_channel
+    ].freeze
+
     LockHeartbeat = Struct.new(:thread, :mutex, :condition, :stop, :ownership_lost) do
       def ownership_lost?
         mutex.synchronize { ownership_lost }
       end
     end
 
-    def initialize(chat:, config:, state:, registry:)
+    def initialize(chat:, config:, state:, registry:, error_reporter:)
       @chat = chat
       @config = config
       @state = state
       @registry = registry
+      @error_reporter = error_reporter
       @slot_mutex = Mutex.new
       @slot_condition = ConditionVariable.new
       @active_slots = Hash.new(0)
@@ -24,42 +32,49 @@ module ChatSDK
     def dispatch(event, adapter:, adapter_name:)
       ChatSDK::Instrumentation.instrument("dispatch.chat_sdk", adapter: adapter_name, event_type: event.type) do
         if %i[message_updated message_deleted].include?(event.type)
-          return execute_event(event, build_thread(event, adapter))
+          return execute_event(event, build_thread(event, adapter), adapter_name: adapter_name)
+        end
+
+        if LIFECYCLE_EVENT_TYPES.include?(event.type)
+          return unless dedupe(event, adapter_name, adapter.concurrency_scope(event))
+
+          return execute_event(event, build_thread(event, adapter), adapter_name: adapter_name)
         end
 
-        return unless dedupe(event, adapter_name)
+        concurrency_scope = adapter.concurrency_scope(event)
+        return unless dedupe(event, adapter_name, concurrency_scope)
 
         thread = build_thread(event, adapter)
-        thread_key = thread_key_for(event, adapter_name)
+        thread_key = thread_key_for(event, adapter_name, concurrency_scope)
         strategy = @config.concurrency[:strategy]
 
         if strategy == :concurrent
-          return with_concurrent_slot(thread_key) { execute_event(event, thread) }
+          return with_concurrent_slot(thread_key) { execute_event(event, thread, adapter_name: adapter_name) }
         end
 
         owner = "#{Process.pid}:#{::Thread.current.object_id}:#{SecureRandom.uuid}"
         if %i[queue burst debounce].include?(strategy)
-          dispatch_queued(event, adapter, thread_key, owner, strategy)
+          dispatch_queued(event, adapter, adapter_name, thread_key, owner, strategy)
         else
-          dispatch_locked(event, thread, thread_key, owner, strategy)
+          dispatch_locked(event, thread, adapter_name, thread_key, owner, strategy)
         end
       end
     end
 
     private
 
-    def dispatch_locked(event, thread, thread_key, owner, strategy)
+    def dispatch_locked(event, thread, adapter_name, thread_key, owner, strategy)
       acquired = acquire_lock(thread_key, event, owner, force: strategy == :force)
       return unless acquired
 
       heartbeat = start_lock_heartbeat(thread_key, owner)
-      execute_event(event, thread)
+      execute_event(event, thread, adapter_name: adapter_name)
     ensure
       stop_lock_heartbeat(heartbeat)
       release_lock(thread_key, owner) if acquired
     end
 
-    def dispatch_queued(event, adapter, thread_key, owner, strategy)
+    def dispatch_queued(event, adapter, adapter_name, thread_key, owner, strategy)
       queue_key = "chat_sdk:queue:#{thread_key}"
       acquired = acquire_lock(thread_key, event, owner, apply_conflict_policy: false)
       pre_enqueued = false
@@ -73,23 +88,23 @@ module ChatSDK
 
       heartbeat = start_lock_heartbeat(thread_key, owner)
       if strategy == :queue
-        execute_event(event, build_thread(event, adapter)) unless pre_enqueued
+        execute_event(event, build_thread(event, adapter), adapter_name: adapter_name) unless pre_enqueued
       else
         enqueue(queue_key, event) unless pre_enqueued
         sleep(@config.concurrency[:debounce].to_f) if strategy == :burst
       end
 
       if strategy == :debounce
-        debounce_loop(queue_key, adapter, heartbeat)
+        debounce_loop(queue_key, adapter, adapter_name, heartbeat)
       else
-        drain_loop(queue_key, adapter, strategy, heartbeat)
+        drain_loop(queue_key, adapter, adapter_name, strategy, heartbeat)
       end
     ensure
       stop_lock_heartbeat(heartbeat)
       release_lock(thread_key, owner) if acquired
     end
 
-    def drain_loop(queue_key, adapter, strategy, heartbeat)
+    def drain_loop(queue_key, adapter, adapter_name, strategy, heartbeat)
       loop do
         break if heartbeat&.ownership_lost?
 
@@ -104,12 +119,12 @@ module ChatSDK
           events[0...-1].filter_map { |queued| queued.message if queued.respond_to?(:message) }
         end
         context = {skipped: skipped, total_since_last_handler: skipped.length + 1}
-        execute_event(current, build_thread(current, adapter), context: context)
+        execute_event(current, build_thread(current, adapter), adapter_name: adapter_name, context: context)
         ::Thread.pass
       end
     end
 
-    def debounce_loop(queue_key, adapter, heartbeat)
+    def debounce_loop(queue_key, adapter, adapter_name, heartbeat)
       skipped = []
       loop do
         sleep(@config.concurrency[:debounce].to_f)
@@ -131,7 +146,7 @@ module ChatSDK
           message.thread_id == latest.thread_id
         end
         context = {skipped: relevant, total_since_last_handler: relevant.length + 1}
-        execute_event(latest, build_thread(latest, adapter), context: context)
+        execute_event(latest, build_thread(latest, adapter), adapter_name: adapter_name, context: context)
         skipped.clear
       end
     end
@@ -155,12 +170,12 @@ module ChatSDK
       end
     end
 
-    def dedupe(event, adapter_name)
+    def dedupe(event, adapter_name, concurrency_scope)
       event_id = extract_event_id(event)
       return true unless event_id
 
       is_new = @state.set_if_absent(
-        "chat_sdk:dedupe:#{adapter_name}:#{event_id}",
+        dedupe_key(adapter_name, concurrency_scope, event_id),
         true,
         ttl: @config.dedupe_ttl
       )
@@ -178,12 +193,18 @@ module ChatSDK
       end
     end
 
-    def thread_key_for(event, adapter_name)
+    def dedupe_key(adapter_name, concurrency_scope, event_id)
+      prefix = ["chat_sdk:dedupe", adapter_name]
+      prefix << concurrency_scope if concurrency_scope
+      "#{prefix.join(":")}:#{event_id}"
+    end
+
+    def thread_key_for(event, adapter_name, concurrency_scope)
       channel_id = event.respond_to?(:channel_id) ? event.channel_id : nil
       thread_id = event.respond_to?(:thread_id) ? event.thread_id : nil
       lock_scope = @config.concurrency[:lock_scope]
       scope_id = (lock_scope&.to_sym == :channel) ? channel_id : thread_id
-      "#{adapter_name}:#{channel_id}:#{scope_id}"
+      [adapter_name, concurrency_scope, channel_id, scope_id].compact.join(":")
     end
 
     def acquire_lock(thread_key, event, owner, force: false, apply_conflict_policy: true)
@@ -255,29 +276,87 @@ module ChatSDK
       ChatSDK::Thread.new(id: thread_id, channel_id: channel_id, adapter: adapter, chat: @chat, current_message: current_message)
     end
 
-    def execute_event(event, thread, context: nil)
+    def execute_event(event, thread, adapter_name:, context: nil)
+      if %i[mention subscribed_message direct_message].include?(event.type)
+        route_message_event(event, thread, adapter_name, context)
+        return
+      end
+
       @registry.handlers_for(event).each do |handler|
-        execute_handler(handler, event, thread, context: context)
+        execute_handler(handler, event, thread, adapter_name: adapter_name, context: context)
       end
     end
 
-    def execute_handler(handler, event, thread, context: nil)
+    def route_message_event(event, thread, adapter_name, context)
+      message = event.message
+      dm_handlers = @registry.handlers_for_type(:direct_message, event: event)
+      if event.type == :direct_message && dm_handlers.any?
+        run_handlers(dm_handlers, event, thread, adapter_name, context)
+        return
+      end
+
+      message.is_mention = true if event.type == :direct_message
+
+      if thread&.subscribed?
+        run_handlers(@registry.handlers_for_type(:subscribed_message, event: event), event, thread, adapter_name, context)
+        return
+      end
+
+      if message.is_mention.nil?
+        message.is_mention = if event.type == :mention
+          true
+        else
+          detect_mention(message.text)
+        end
+      end
+
+      if message.is_mention
+        run_handlers(@registry.handlers_for_type(:mention, event: event), event, thread, adapter_name, context)
+        return
+      end
+
+      @registry.handlers_for_type(:new_message, event: event).each do |handler|
+        execute_handler(handler, event, thread, adapter_name: adapter_name, context: context)
+      end
+    end
+
+    def run_handlers(handlers, event, thread, adapter_name, context)
+      handlers.each do |handler|
+        execute_handler(handler, event, thread, adapter_name: adapter_name, context: context)
+      end
+    end
+
+    def detect_mention(text)
+      masked_text = ChatSDK::Format::Mentions.mask_code_spans(text)
+      /(?<![[:word:]])@#{Regexp.escape(@config.user_name)}\b/i.match?(masked_text)
+    end
+
+    def execute_handler(handler, event, thread, adapter_name:, context: nil)
       ChatSDK::Instrumentation.instrument("handler.chat_sdk", handler_type: event.type) do
         ChatSDK::AI::ConversationScope.with(thread) do
           case event.type
-          when :mention, :subscribed_message, :direct_message
+          when :mention, :subscribed_message, :direct_message, :new_message
             handler.block.call(thread, event.message, context)
           when :message_updated
             handler.block.call(thread, event.message, event.previous_message)
-          when :reaction, :action, :slash_command, :message_deleted
+          when :reaction, :action, :slash_command, :message_deleted, :installed, :uninstalled
             add_thread_to_event(event, thread)
             handler.block.call(event)
+          when *LIFECYCLE_EVENT_TYPES
+            handler.block.call(event)
           end
         end
       end
     rescue => e
-      ChatSDK::Log.error("Handler error (#{event.type}): #{e.message}")
-      ChatSDK::Log.debug(e.backtrace&.first(5)&.join("\n"))
+      @error_reporter.report(
+        e,
+        "Handler error (#{event.type})",
+        source: :handler,
+        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
 
     def add_thread_to_event(event, thread)

data/lib/chat_sdk/error_reporter.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  class ErrorReporter
+    def initialize(callback = nil)
+      @callback = callback
+    end
+
+    def report(error, message, **context)
+      context = context.compact
+      ChatSDK::Log.error(format_entry(error, message, context))
+      reporter = @callback || self.class.default_callback
+      reporter&.call(error, context)
+    rescue => e
+      ChatSDK::Log.error("on_error callback failed: #{e.class}: #{e.message}")
+    end
+
+    def self.default_callback
+      return unless defined?(::Rails) && ::Rails.respond_to?(:error)
+
+      rails_reporter = ::Rails.error
+      return unless rails_reporter.respond_to?(:report)
+
+      ->(error, context) { rails_reporter.report(error, handled: true, severity: :error, context: context) }
+    end
+
+    private
+
+    def format_entry(error, message, context)
+      details = context.empty? ? "" : " (#{context.map { |key, value| "#{key}=#{value}" }.join(" ")})"
+      entry = "#{message}#{details}: #{error.class}: #{error.message}"
+      backtrace = error.backtrace
+      backtrace ? "#{entry}\n#{backtrace.join("\n")}" : entry
+    end
+  end
+end

data/lib/chat_sdk/errors.rb

@@ -15,6 +15,7 @@ module ChatSDK
 
   class LockConflictError < Error; end
   class SignatureVerificationError < Error; end
+  class HandlerExecutorError < Error; end
 
   class PlatformError < Error
     attr_reader :status, :body, :adapter_name

data/lib/chat_sdk/event_registry.rb

@@ -13,13 +13,18 @@ module ChatSDK
     end
 
     def handlers_for(event)
-      @handlers.select { |h| matches?(h, event) }
+      handlers_for_type(event.type, event: event)
+    end
+
+    def handlers_for_type(type, event: nil)
+      @handlers.select do |handler|
+        handler.type == type && (!event || matches?(handler, event))
+      end
     end
 
     private
 
     def matches?(handler, event)
-      return false unless handler.type == event.type
       return true if handler.matcher.nil?
 
       case handler.matcher

data/lib/chat_sdk/event_serializer.rb

@@ -16,14 +16,35 @@ module ChatSDK
           data.merge!(
             "message_id" => event.message_id,
             "previous_message" => dump_message(event.previous_message),
-            "deleted_at" => event.deleted_at&.iso8601
+            "deleted_at" => event.deleted_at&.iso8601(6)
           )
         when :reaction
           data.merge!("emoji" => event.emoji, "user_id" => event.user_id, "message_id" => event.message_id, "added" => event.added?)
         when :action
-          data.merge!("action_id" => event.action_id, "value" => event.value, "user" => dump_author(event.user), "trigger_id" => event.trigger_id)
+          data.merge!("action_id" => event.action_id, "value" => event.value, "values" => json_safe(event.values), "user" => dump_author(event.user), "trigger_id" => event.trigger_id)
         when :slash_command
           data.merge!("command" => event.command, "text" => event.text, "user_id" => event.user_id, "trigger_id" => event.trigger_id)
+        when :installed, :uninstalled
+          data.merge!(
+            "installation_id" => event.installation_id,
+            "team_id" => event.team_id,
+            "tenant_id" => event.tenant_id,
+            "conversation_id" => event.conversation_id,
+            "action" => event.action,
+            "user" => dump_author(event.user)
+          )
+        when :assistant_thread_started, :assistant_context_changed
+          data.merge!(
+            "thread_ts" => event.thread_ts,
+            "user_id" => event.user_id,
+            "context" => event.context.to_h.transform_keys(&:to_s)
+          )
+        when :app_home_opened
+          data["user_id"] = event.user_id
+          data["tab"] = event.tab
+        when :member_joined_channel
+          data["user_id"] = event.user_id
+          data["inviter_id"] = event.inviter_id
         end
         data
       end
@@ -55,10 +76,45 @@ module ChatSDK
         when :reaction
           Events::Reaction.new(emoji: data["emoji"], user_id: data["user_id"], message_id: data["message_id"], added: data["added"], **common)
         when :action
-          Events::Action.new(action_id: data["action_id"], value: data["value"], user: load_author(data["user"]), trigger_id: data["trigger_id"], **common)
+          Events::Action.new(action_id: data["action_id"], value: data["value"], values: data["values"], user: load_author(data["user"]), trigger_id: data["trigger_id"], **common)
         when :slash_command
           common.delete(:thread_id)
           Events::SlashCommand.new(command: data["command"], text: data["text"], user_id: data["user_id"], trigger_id: data["trigger_id"], **common)
+        when :installed, :uninstalled
+          common.delete(:thread_id)
+          common.delete(:channel_id)
+          event_class = if type == :installed
+            Events::Installed
+          else
+            Events::Uninstalled
+          end
+          event_class.new(
+            installation_id: data["installation_id"],
+            team_id: data["team_id"],
+            tenant_id: data["tenant_id"],
+            conversation_id: data["conversation_id"],
+            action: data["action"],
+            user: load_author(data["user"]),
+            **common
+          )
+        when :assistant_thread_started, :assistant_context_changed
+          event_class = if type == :assistant_thread_started
+            Events::AssistantThreadStarted
+          else
+            Events::AssistantContextChanged
+          end
+          event_class.new(
+            thread_ts: data["thread_ts"],
+            user_id: data["user_id"],
+            context: data["context"] || {},
+            **common
+          )
+        when :app_home_opened
+          common.delete(:thread_id)
+          Events::AppHomeOpened.new(user_id: data["user_id"], tab: data["tab"], **common)
+        when :member_joined_channel
+          common.delete(:thread_id)
+          Events::MemberJoinedChannel.new(user_id: data["user_id"], inviter_id: data["inviter_id"], **common)
         else
           raise ArgumentError, "unsupported queued event type: #{type}"
         end
@@ -74,7 +130,7 @@ module ChatSDK
           "thread_id" => event.respond_to?(:thread_id) ? event.thread_id : nil,
           "channel_id" => event.respond_to?(:channel_id) ? event.channel_id : nil,
           "raw" => json_safe(event.raw),
-          "timestamp" => event.timestamp&.iso8601
+          "timestamp" => event.timestamp&.iso8601(6)
         }
       end
 
@@ -93,7 +149,8 @@ module ChatSDK
           "reply_to" => dump_message(message.reply_to),
           "subject" => json_safe(message.subject),
           "raw" => json_safe(message.raw),
-          "timestamp" => message.timestamp&.iso8601
+          "timestamp" => message.timestamp&.iso8601(6),
+          "is_mention" => message.is_mention
         }
       end
 
@@ -113,7 +170,8 @@ module ChatSDK
           reply_to: load_message(data["reply_to"]),
           subject: data["subject"],
           raw: data["raw"],
-          timestamp: parse_time(data["timestamp"])
+          timestamp: parse_time(data["timestamp"]),
+          is_mention: data["is_mention"]
         )
       end
 
@@ -125,6 +183,7 @@ module ChatSDK
           "name" => author.name,
           "platform" => author.platform.to_s,
           "bot" => author.bot?,
+          "me" => author.me?,
           "system" => author.system?,
           "locale" => author.locale,
           "email" => author.email,
@@ -141,6 +200,7 @@ module ChatSDK
           name: data["name"],
           platform: data["platform"].to_sym,
           bot: data["bot"],
+          me: data["me"],
           system: data["system"],
           locale: data["locale"],
           email: data["email"],

data/lib/chat_sdk/events/action.rb

@@ -3,13 +3,14 @@
 module ChatSDK
   module Events
     class Action < Base
-      attr_reader :action_id, :value, :user, :thread_id, :channel_id, :trigger_id
+      attr_reader :action_id, :value, :values, :user, :thread_id, :channel_id, :trigger_id
       attr_accessor :thread
 
-      def initialize(action_id:, thread_id:, channel_id:, value: nil, user: nil, trigger_id: nil, **kwargs)
+      def initialize(action_id:, thread_id:, channel_id:, value: nil, values: nil, user: nil, trigger_id: nil, **kwargs)
         super(type: :action, **kwargs)
         @action_id = action_id
         @value = value
+        @values = values
         @user = user
         @thread_id = thread_id
         @channel_id = channel_id

data/lib/chat_sdk/events/app_home_opened.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Events
+    class AppHomeOpened < Base
+      attr_reader :user_id, :channel_id, :tab
+
+      def initialize(user_id:, channel_id:, tab: nil, **kwargs)
+        super(type: :app_home_opened, **kwargs)
+        @user_id = user_id
+        @channel_id = channel_id
+        @tab = tab
+      end
+    end
+  end
+end

data/lib/chat_sdk/events/assistant_context.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Events
+    # rubocop:disable Style/RedundantStructKeywordInit
+    AssistantContext = Struct.new(
+      :channel_id,
+      :team_id,
+      :enterprise_id,
+      :thread_entry_point,
+      :force_search,
+      keyword_init: true
+    )
+    # rubocop:enable Style/RedundantStructKeywordInit
+
+    def AssistantContext.coerce(value)
+      return value if value.is_a?(self)
+
+      value = {} if value.nil?
+      return value unless value.is_a?(Hash)
+
+      new(**value.transform_keys(&:to_sym).slice(*members))
+    end
+  end
+end

data/lib/chat_sdk/events/assistant_context_changed.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Events
+    class AssistantContextChanged < Base
+      attr_reader :thread_id, :channel_id, :thread_ts, :user_id, :context
+
+      def initialize(thread_id:, channel_id:, thread_ts:, user_id:, context: {}, **kwargs)
+        super(type: :assistant_context_changed, **kwargs)
+        @thread_id = thread_id
+        @channel_id = channel_id
+        @thread_ts = thread_ts
+        @user_id = user_id
+        @context = AssistantContext.coerce(context)
+      end
+    end
+  end
+end

data/lib/chat_sdk/events/assistant_thread_started.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Events
+    class AssistantThreadStarted < Base
+      attr_reader :thread_id, :channel_id, :thread_ts, :user_id, :context
+
+      def initialize(thread_id:, channel_id:, thread_ts:, user_id:, context: {}, **kwargs)
+        super(type: :assistant_thread_started, **kwargs)
+        @thread_id = thread_id
+        @channel_id = channel_id
+        @thread_ts = thread_ts
+        @user_id = user_id
+        @context = AssistantContext.coerce(context)
+      end
+    end
+  end
+end

data/lib/chat_sdk/events/installed.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Events
+    class Installed < Base
+      attr_reader :installation_id, :team_id, :tenant_id, :conversation_id, :action, :user
+
+      def initialize(conversation_id:, action:, installation_id: nil, team_id: nil, tenant_id: nil, user: nil, **kwargs)
+        super(type: :installed, **kwargs)
+        @installation_id = installation_id
+        @team_id = team_id
+        @tenant_id = tenant_id
+        @conversation_id = conversation_id
+        @action = action
+        @user = user
+      end
+    end
+  end
+end

data/lib/chat_sdk/events/member_joined_channel.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Events
+    class MemberJoinedChannel < Base
+      attr_reader :user_id, :channel_id, :inviter_id
+
+      def initialize(user_id:, channel_id:, inviter_id: nil, **kwargs)
+        super(type: :member_joined_channel, **kwargs)
+        @user_id = user_id
+        @channel_id = channel_id
+        @inviter_id = inviter_id
+      end
+    end
+  end
+end

data/lib/chat_sdk/events/uninstalled.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Events
+    class Uninstalled < Base
+      attr_reader :installation_id, :team_id, :tenant_id, :conversation_id, :action, :user
+
+      def initialize(conversation_id:, action:, installation_id: nil, team_id: nil, tenant_id: nil, user: nil, **kwargs)
+        super(type: :uninstalled, **kwargs)
+        @installation_id = installation_id
+        @team_id = team_id
+        @tenant_id = tenant_id
+        @conversation_id = conversation_id
+        @action = action
+        @user = user
+      end
+    end
+  end
+end

data/lib/chat_sdk/format/mentions.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Format
+    module Mentions
+      class << self
+        def mask_code_spans(text)
+          characters = text.to_s.chars
+          masked = characters.dup
+          opening = nil
+          opening_length = nil
+          fence = false
+          index = 0
+
+          while index < characters.length
+            if characters[index] == "`"
+              finish = index + 1
+              finish += 1 while finish < characters.length && characters[finish] == "`"
+              length = finish - index
+
+              if opening
+                closes = fence ? length >= 3 : length == opening_length
+                if closes
+                  blank_span(masked, opening, finish)
+                  opening = nil
+                  opening_length = nil
+                  fence = false
+                else
+                  blank_span(masked, index, finish)
+                end
+              else
+                opening = index
+                opening_length = length
+                fence = length >= 3
+                blank_span(masked, index, finish)
+              end
+
+              index = finish
+            else
+              if opening
+                masked[index] = " " unless characters[index] == "\n" || characters[index] == "\r"
+              end
+              index += 1
+            end
+          end
+
+          masked[opening..] = characters[opening..] if opening
+          masked.join
+        end
+
+        private
+
+        def blank_span(characters, first, finish)
+          (first...finish).each do |index|
+            characters[index] = " " unless characters[index] == "\n" || characters[index] == "\r"
+          end
+        end
+      end
+    end
+  end
+end