chat_sdk 1.1.0 → 1.3.0

data/lib/chat_sdk/message.rb

@@ -4,9 +4,11 @@ module ChatSDK
   class Message
     attr_reader :id, :text, :author, :thread_id, :channel_id,
       :platform, :attachments, :links, :reply_to, :subject, :raw, :timestamp
+    attr_accessor :is_mention
 
     def initialize(id:, text:, author:, thread_id:, channel_id:, platform:,
-      attachments: [], links: [], reply_to: nil, subject: nil, raw: nil, timestamp: nil)
+      attachments: [], links: [], reply_to: nil, subject: nil, raw: nil,
+      timestamp: nil, is_mention: nil)
       @id = id
       @text = text
       @author = author
@@ -19,6 +21,7 @@ module ChatSDK
       @subject = subject
       @raw = raw
       @timestamp = timestamp
+      @is_mention = is_mention
     end
 
     def ==(other)

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/postable_message.rb

@@ -2,14 +2,15 @@
 
 module ChatSDK
   class PostableMessage
-    attr_reader :text, :card, :attachments, :metadata
+    attr_reader :text, :card, :attachments, :metadata, :ai_generated
 
-    def initialize(text: nil, card: nil, attachments: [], metadata: {})
+    def initialize(text: nil, card: nil, attachments: [], metadata: {}, ai_generated: false)
       raise ArgumentError, "text or card required" if text.nil? && card.nil?
       @text = text
       @card = card
       @attachments = attachments
       @metadata = metadata
+      @ai_generated = ai_generated
     end
 
     def card?

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

@@ -3,39 +3,74 @@
 module ChatSDK
   module Streaming
     class Stream
+      include ChatSDK::Adapter::Invocation
+
       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
 
@@ -50,18 +85,23 @@ module ChatSDK
         return if @buffer.empty?
 
         if @message_id && adapter.supports?(:edit_messages)
-          adapter.edit_message(
+          call_adapter(
+            :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/testing/fake_adapter.rb

@@ -50,7 +50,7 @@ module ChatSDK
         )
       end
 
-      def edit_message(channel_id:, message_id:, message:)
+      def edit_message(channel_id:, message_id:, message:, **_options)
         record = RecordedCall.new(:edit_message, channel_id: channel_id, message_id: message_id, message: message)
         @edited_messages << record
         record
@@ -68,7 +68,7 @@ module ChatSDK
         record
       end
 
-      def delete_message(channel_id:, message_id:)
+      def delete_message(channel_id:, message_id:, **_options)
         record = RecordedCall.new(:delete_message, channel_id: channel_id, message_id: message_id)
         @deleted_messages << record
         record
@@ -86,13 +86,13 @@ module ChatSDK
         record
       end
 
-      def add_reaction(channel_id:, message_id:, emoji:)
+      def add_reaction(channel_id:, message_id:, emoji:, **_options)
         record = RecordedCall.new(:add_reaction, channel_id: channel_id, message_id: message_id, emoji: emoji)
         @reactions_added << record
         record
       end
 
-      def remove_reaction(channel_id:, message_id:, emoji:)
+      def remove_reaction(channel_id:, message_id:, emoji:, **_options)
         record = RecordedCall.new(:remove_reaction, channel_id: channel_id, message_id: message_id, emoji: emoji)
         @reactions_removed << record
         record
@@ -122,8 +122,8 @@ module ChatSDK
         record
       end
 
-      def start_typing(channel_id:, thread_id: nil)
-        record = RecordedCall.new(:start_typing, channel_id: channel_id, thread_id: thread_id)
+      def start_typing(channel_id:, thread_id: nil, message_id: nil)
+        record = RecordedCall.new(:start_typing, channel_id: channel_id, thread_id: thread_id, message_id: message_id)
         @typing_started << record
         record
       end

data/lib/chat_sdk/thread.rb

@@ -2,6 +2,8 @@
 
 module ChatSDK
   class Thread
+    include Adapter::Invocation
+
     attr_reader :id, :channel_id, :adapter, :chat, :current_message
 
     def initialize(id:, channel_id:, adapter:, chat:, current_message: nil)
@@ -25,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
@@ -51,41 +55,54 @@ module ChatSDK
       adapter.mark_as_read(channel_id: channel_id, thread_id: id, message_id: message_id, message: target.is_a?(ChatSDK::Message) ? target : nil)
     end
 
+    def start_typing
+      adapter.start_typing(channel_id: channel_id, thread_id: id, message_id: current_message&.id)
+    end
+
     def post_ephemeral(content, user_id:)
       message = PostableMessage.from(content)
       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)
       message = PostableMessage.from(content)
-      adapter.edit_message(channel_id: channel_id, message_id: message_id, message: message)
+      call_adapter(:edit_message, channel_id: channel_id, message_id: message_id, message: message, thread_id: id)
     end
 
     def delete(message_id)
-      adapter.delete_message(channel_id: channel_id, message_id: message_id)
+      call_adapter(:delete_message, channel_id: channel_id, message_id: message_id, thread_id: id)
     end
 
     def react(message_id, emoji)
-      adapter.add_reaction(channel_id: channel_id, message_id: message_id, emoji: emoji)
+      call_adapter(:add_reaction, channel_id: channel_id, message_id: message_id, emoji: emoji, thread_id: id)
     end
 
     def unreact(message_id, emoji)
-      adapter.remove_reaction(channel_id: channel_id, message_id: message_id, emoji: emoji)
+      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)
@@ -123,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.1.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,16 +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 = 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

data/lib/chat_sdk.rb

@@ -17,8 +17,8 @@ module ChatSDK
       end
     end
 
-    def card(title: nil, subtitle: nil, width: nil, &block)
-      Cards::Builder.new(title: title, subtitle: subtitle, width: width, &block).build
+    def card(title: nil, subtitle: nil, width: nil, image_url: nil, &block)
+      Cards::Builder.new(title: title, subtitle: subtitle, width: width, image_url: image_url, &block).build
     end
   end
 end