chat_sdk 1.2.0 → 1.3.0

data/lib/chat_sdk/event_serializer.rb

@@ -16,7 +16,7 @@ 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?)
@@ -33,6 +33,18 @@ module ChatSDK
             "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
@@ -85,6 +97,24 @@ module ChatSDK
             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
@@ -100,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
 
@@ -119,7 +149,7 @@ 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

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/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/modals/builder.rb

@@ -3,10 +3,11 @@
 module ChatSDK
   module Modals
     class Builder
-      def initialize(title:, submit_label: nil, callback_id: nil, &block)
+      def initialize(title:, submit_label: nil, callback_id: nil, close_label: nil, &block)
         @title = title
         @submit_label = submit_label
         @callback_id = callback_id
+        @close_label = close_label
         @children = []
         instance_eval(&block) if block
       end
@@ -15,23 +16,57 @@ module ChatSDK
         attrs = {title: @title}
         attrs[:submit_label] = @submit_label if @submit_label
         attrs[:callback_id] = @callback_id if @callback_id
+        attrs[:close_label] = @close_label if @close_label
         ChatSDK::Cards::Node.new(:modal, attributes: attrs, children: @children)
       end
 
-      def text_input(id:, label:, placeholder: nil, multiline: false, optional: false)
+      def text_input(id:, label:, placeholder: nil, multiline: false, optional: false, initial_value: nil, max_length: nil)
         attrs = {id: id, label: label, input_type: :text, multiline: multiline, optional: optional}
         attrs[:placeholder] = placeholder if placeholder
+        attrs[:initial_value] = initial_value unless initial_value.nil?
+        attrs[:max_length] = max_length unless max_length.nil?
         @children << ChatSDK::Cards::Node.new(:input, attributes: attrs)
       end
 
-      def select_input(id:, label:, placeholder: nil, optional: false, &block)
+      def select_input(id:, label:, placeholder: nil, optional: false, initial_option: nil, dispatch_action: nil, &block)
         ctx = ChatSDK::Cards::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, label: label, input_type: :select, optional: optional}
         attrs[:placeholder] = placeholder if placeholder
+        attrs[:initial_option] = initial_option unless initial_option.nil?
+        attrs[:dispatch_action] = dispatch_action unless dispatch_action.nil?
+        @children << ChatSDK::Cards::Node.new(:input, attributes: attrs, children: ctx.nodes)
+      end
+
+      def radio_select_input(id:, label:, initial_option: nil, optional: nil, dispatch_action: nil, &block)
+        ctx = ChatSDK::Cards::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, input_type: :radio_select}
+        attrs[:initial_option] = initial_option unless initial_option.nil?
+        attrs[:optional] = optional unless optional.nil?
+        attrs[:dispatch_action] = dispatch_action unless dispatch_action.nil?
         @children << ChatSDK::Cards::Node.new(:input, attributes: attrs, children: ctx.nodes)
       end
 
+      def external_select_input(id:, label:, placeholder: nil, min_query_length: nil, initial_option: nil, optional: nil)
+        attrs = {id: id, label: label, input_type: :external_select}
+        attrs[:placeholder] = placeholder if placeholder
+        attrs[:min_query_length] = min_query_length unless min_query_length.nil?
+        attrs[:initial_option] = initial_option unless initial_option.nil?
+        attrs[:optional] = optional unless optional.nil?
+        @children << ChatSDK::Cards::Node.new(:input, attributes: attrs)
+      end
+
+      def fields(&block)
+        ctx = ChatSDK::Cards::FieldsContext.new
+        ctx.instance_eval(&block)
+        @children << ChatSDK::Cards::Node.new(:fields, children: ctx.nodes)
+      end
+
       def date_input(id:, label:, initial_value: nil, placeholder: nil, optional: false)
         attrs = {id: id, label: label, input_type: :date, optional: optional}
         attrs[:initial_value] = initial_value if initial_value

data/lib/chat_sdk/streaming/chunk.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Streaming
+    module Chunk
+      module_function
+
+      def normalize(value)
+        return value if value.is_a?(MarkdownTextChunk) || value.is_a?(TaskUpdateChunk) || value.is_a?(PlanUpdateChunk)
+
+        if value.is_a?(Hash)
+          type = value[:type] || value["type"]
+          attributes = value.each_with_object({}) do |(key, entry), result|
+            result[key.to_sym] = entry
+          end
+
+          return MarkdownTextChunk.new(text: attributes[:text]) if type.to_s == "markdown_text"
+          return TaskUpdateChunk.new(**attributes.except(:type)) if type.to_s == "task_update"
+          return PlanUpdateChunk.new(**attributes.except(:type)) if type.to_s == "plan_update"
+
+          return nil
+        end
+
+        value.to_s
+      end
+
+      def text_of(value)
+        case value
+        when String then value
+        when MarkdownTextChunk then value.text
+        end
+      end
+    end
+  end
+end

data/lib/chat_sdk/streaming/markdown_text_chunk.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Streaming
+    MarkdownTextChunk = Data.define(:text) do
+      def type
+        "markdown_text"
+      end
+
+      def to_h
+        {type: type, text: text}
+      end
+    end
+  end
+end

data/lib/chat_sdk/streaming/plan_update_chunk.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Streaming
+    PlanUpdateChunk = Data.define(:title) do
+      def type
+        "plan_update"
+      end
+
+      def to_h
+        {type: type, title: title}
+      end
+    end
+  end
+end

data/lib/chat_sdk/streaming/stream.rb

@@ -7,37 +7,70 @@ module ChatSDK
 
       attr_reader :adapter, :channel_id, :thread_id, :update_interval
 
-      def initialize(adapter:, channel_id:, thread_id:, placeholder: nil, update_interval: 0.5)
+      def initialize(adapter:, channel_id:, thread_id:, placeholder: nil, update_interval: 0.5, ai_generated: false)
         @adapter = adapter
         @channel_id = channel_id
         @thread_id = thread_id
         @placeholder = placeholder
         @update_interval = update_interval
+        @ai_generated = ai_generated
         @buffer = +""
+        @delivered_text = +""
         @message_id = nil
+        @message = nil
         @last_flush_at = nil
       end
 
       def <<(chunk)
-        @buffer << chunk.to_s
+        text = Chunk.text_of(Chunk.normalize(chunk))
+        return self unless text
+
+        @buffer << text
         maybe_flush
         self
       end
 
-      def run(&block)
+      def run(source = nil, &block)
         post_placeholder if @placeholder
-        yield self
+        if source
+          source.each { |chunk| self << chunk }
+        elsif block
+          block.call(self)
+        end
         flush
+        message_with_text(@message, @delivered_text)
       end
 
       private
 
+      def message_with_text(message, text)
+        return unless message
+
+        ChatSDK::Message.new(
+          id: message.id,
+          text: text.dup,
+          author: message.author,
+          thread_id: message.thread_id,
+          channel_id: message.channel_id,
+          platform: message.platform,
+          attachments: message.attachments,
+          links: message.links,
+          reply_to: message.reply_to,
+          subject: message.subject,
+          raw: message.raw,
+          timestamp: message.timestamp,
+          is_mention: message.is_mention
+        )
+      end
+
       def post_placeholder
         result = adapter.post_message(
           channel_id: channel_id,
-          message: PostableMessage.new(text: @placeholder),
+          message: PostableMessage.new(text: @placeholder, ai_generated: @ai_generated),
           thread_id: thread_id
         )
+        @delivered_text = @placeholder.dup
+        @message = result if result.is_a?(ChatSDK::Message)
         @message_id = result.id if result.respond_to?(:id)
       end
 
@@ -56,16 +89,19 @@ module ChatSDK
             :edit_message,
             channel_id: channel_id,
             message_id: @message_id,
-            message: PostableMessage.new(text: @buffer.dup),
+            message: PostableMessage.new(text: @buffer.dup, ai_generated: @ai_generated),
             thread_id: thread_id
           )
+          @delivered_text = @buffer.dup
         elsif !@message_id
           result = adapter.post_message(
             channel_id: channel_id,
-            message: PostableMessage.new(text: @buffer.dup),
+            message: PostableMessage.new(text: @buffer.dup, ai_generated: @ai_generated),
             thread_id: thread_id
           )
+          @message = result if result.is_a?(ChatSDK::Message)
           @message_id = result.id if result.respond_to?(:id)
+          @delivered_text = @buffer.dup
         end
 
         @last_flush_at = Time.now.to_f

data/lib/chat_sdk/streaming/task_update_chunk.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Streaming
+    TASK_UPDATE_STATUSES = %w[pending in_progress complete error].freeze
+    private_constant :TASK_UPDATE_STATUSES
+
+    TaskUpdateChunk = Data.define(:id, :title, :status, :details, :output) do
+      def initialize(id:, title:, status:, details: nil, output: nil)
+        unless TASK_UPDATE_STATUSES.include?(status.to_s)
+          raise ArgumentError, "status must be one of #{TASK_UPDATE_STATUSES.join(", ")}"
+        end
+
+        super(id: id, title: title, status: status.to_s, details: details, output: output)
+      end
+
+      def type
+        "task_update"
+      end
+
+      def to_h
+        {type: type, id: id, title: title, status: status, details: details, output: output}.compact
+      end
+    end
+  end
+end

data/lib/chat_sdk/streaming/writer.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Streaming
+    class Writer
+      def initialize(yielder)
+        @yielder = yielder
+      end
+
+      def <<(chunk)
+        @yielder << chunk
+        self
+      end
+    end
+  end
+end

data/lib/chat_sdk/streaming_plan.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  class StreamingPlan
+    GROUP_TASKS = %w[plan timeline].freeze
+
+    attr_reader :stream, :options
+
+    def initialize(stream, group_tasks: nil, end_with: nil, update_interval: nil, ai_generated: false)
+      if group_tasks && !GROUP_TASKS.include?(group_tasks.to_s)
+        raise ArgumentError, "group_tasks must be :plan or :timeline"
+      end
+
+      @stream = stream
+      @options = {
+        group_tasks: group_tasks&.to_s,
+        end_with: end_with,
+        update_interval: update_interval,
+        ai_generated: ai_generated
+      }.compact
+    end
+
+    def to_stream_options
+      {
+        task_display_mode: options[:group_tasks],
+        stop_blocks: options[:end_with],
+        update_interval: options[:update_interval],
+        ai_generated: (true if options[:ai_generated])
+      }.compact
+    end
+  end
+end

data/lib/chat_sdk/thread.rb

@@ -27,6 +27,8 @@ module ChatSDK
     end
 
     def post(content)
+      return handle_stream(content.stream, content.to_stream_options) if content.is_a?(StreamingPlan)
+
       message = PostableMessage.from(content)
       adapter.post_message(channel_id: channel_id, message: message, thread_id: id)
     end
@@ -62,15 +64,24 @@ module ChatSDK
       adapter.post_ephemeral(channel_id: channel_id, user_id: user_id, message: message, thread_id: id)
     end
 
-    def post_stream(placeholder: nil, &block)
-      stream = Streaming::Stream.new(
-        adapter: adapter,
-        channel_id: channel_id,
-        thread_id: id,
-        placeholder: placeholder,
-        update_interval: chat.config.streaming_update_interval
-      )
-      stream.run(&block)
+    def post_stream(source = nil, placeholder: nil, **plan_options, &block)
+      raise ArgumentError, "provide either a stream source or a block" if !source.nil? && block
+      raise ArgumentError, "a stream source or block is required" if source.nil? && !block
+
+      if block
+        source = Enumerator.new do |yielder|
+          block.call(Streaming::Writer.new(yielder))
+        end
+      end
+
+      if source.is_a?(StreamingPlan)
+        options = StreamingPlan.new(source.stream, **source.options.merge(plan_options)).to_stream_options
+        source = source.stream
+      else
+        options = StreamingPlan.new(source, **plan_options).to_stream_options
+      end
+
+      handle_stream(source, options.merge(placeholder: placeholder))
     end
 
     def edit(message_id, content)
@@ -90,8 +101,8 @@ module ChatSDK
       call_adapter(:remove_reaction, channel_id: channel_id, message_id: message_id, emoji: emoji, thread_id: id)
     end
 
-    def post_ai_stream(enumerable, placeholder: "Thinking...")
-      ChatSDK::AI::StreamHandler.stream_to_thread(self, enumerable, placeholder: placeholder)
+    def post_ai_stream(enumerable, placeholder: "Thinking...", **plan_options)
+      ChatSDK::AI::StreamHandler.stream_to_thread(self, enumerable, placeholder: placeholder, **plan_options)
     end
 
     def upload(io:, filename:, comment: nil)
@@ -129,6 +140,60 @@ module ChatSDK
 
     private
 
+    def handle_stream(source, caller_options)
+      options = caller_options.merge(
+        update_interval: caller_options[:update_interval] || chat.config.streaming_update_interval
+      )
+      if current_message
+        options[:recipient_user_id] = current_message.author&.id
+        options[:recipient_team_id] = extract_recipient_team_id(current_message.raw)
+      end
+      options = options.reject { |_, value| value.nil? }
+      normalized_source = Enumerator.new do |yielder|
+        source.each do |item|
+          chunk = Streaming::Chunk.normalize(item)
+          yielder << chunk unless chunk.nil?
+        end
+      end
+
+      if adapter.respond_to?(:stream)
+        native_message = adapter.stream(
+          channel_id: channel_id,
+          thread_id: id,
+          stream: normalized_source,
+          options: options
+        )
+        return native_message if native_message
+      end
+
+      text_source = Enumerator.new do |yielder|
+        normalized_source.each do |item|
+          text = Streaming::Chunk.text_of(item)
+          yielder << text if text
+        end
+      end
+      Streaming::Stream.new(
+        adapter: adapter,
+        channel_id: channel_id,
+        thread_id: id,
+        placeholder: options[:placeholder],
+        update_interval: options[:update_interval],
+        ai_generated: options[:ai_generated] || false
+      ).run(text_source)
+    end
+
+    def extract_recipient_team_id(raw)
+      return unless raw.is_a?(Hash)
+
+      team_id = raw[:team_id] || raw["team_id"]
+      team = raw[:team] || raw["team"]
+      user = raw[:user] || raw["user"]
+      team_id ||= team if team.is_a?(String)
+      team_id ||= team[:id] || team["id"] if team.is_a?(Hash)
+      team_id ||= user[:team_id] || user["team_id"] if user.is_a?(Hash)
+      team_id if team_id.is_a?(String) && !team_id.empty?
+    end
+
     def state_key(suffix = nil)
       base = "#{adapter.name}:#{channel_id}:#{id}"
       suffix ? "#{base}:#{suffix}" : base

data/lib/chat_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ChatSDK
-  VERSION = "1.2.0"
+  VERSION = "1.3.0"
 end

data/lib/chat_sdk/webhook/endpoint.rb

@@ -12,6 +12,7 @@ module ChatSDK
       end
 
       def call(env)
+        current_event = nil
         request = Rack::Request.new(env) if defined?(Rack)
 
         adapter.verify_request!(request || env)
@@ -20,19 +21,58 @@ module ChatSDK
         return ack if ack
 
         events = adapter.parse_events(request || env)
-        events.each { |event| chat.dispatch(event, adapter_name: adapter_name) }
+        events.each do |event|
+          current_event = event
+          chat.dispatch(event, adapter_name: adapter_name)
+        end
 
-        response = adapter.webhook_response(events)
+        response = if webhook_response_accepts_request?
+          adapter.webhook_response(events, request || env)
+        else
+          adapter.webhook_response(events)
+        end
         return response if response
 
         [200, {"content-type" => "text/plain"}, [""]]
       rescue ChatSDK::SignatureVerificationError => e
         ChatSDK::Log.warn("Signature verification failed: #{e.message}")
         [401, {"content-type" => "text/plain"}, ["Unauthorized"]]
+      rescue ChatSDK::HandlerExecutorError => e
+        chat.error_reporter.report(
+          e,
+          "Handler executor error",
+          **error_context(source: :executor, event: current_event)
+        )
+        # Platforms redeliver non-2xx responses; handlers did not run in this request, and workers deduplicate already-enqueued events.
+        [500, {"content-type" => "text/plain"}, [""]]
       rescue => e
-        ChatSDK::Log.error("Webhook error: #{e.message}")
+        chat.error_reporter.report(
+          e,
+          "Webhook error",
+          **error_context(source: :webhook, event: current_event)
+        )
+        # Platforms retry non-2xx responses, which can repeat handler side effects.
+        # Logging and on_error surface failures without causing a redelivery.
         [200, {"content-type" => "text/plain"}, [""]]
       end
+
+      private
+
+      def webhook_response_accepts_request?
+        parameters = adapter.method(:webhook_response).parameters
+        parameters.any? { |type, _| type == :rest } ||
+          parameters.count { |type, _| %i[req opt].include?(type) } > 1
+      end
+
+      def error_context(source:, event:)
+        {
+          source: source,
+          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
   end
 end