chat_sdk 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a031721bc3de18dd4f5c698516625486a29eb8535397c47ee12e9a2464e2d39
-  data.tar.gz: d01aa8c75630575d3a28b12d37f2072e163575c244b801ad963eeeffe2887469
+  metadata.gz: 36c07ba6e29c7d1cf858767caca271826418d829547426f1677a32c94133205e
+  data.tar.gz: 0a00e35abebb7f43b8c9bb68576fce634d46088430029b33ad7f63c2d3820bbb
 SHA512:
-  metadata.gz: 359f6f5fbae354a23d5f74b9ee2c99c8c24c1b41c07cb77aeb12c289b439314588907ca1ae08b47b0b0b6a601586a7e70e39c3e54157e3062ff289440d2a8eb8
-  data.tar.gz: 6fc8824b5350703d05b96bbea9adae730f7769089dbed78f5abf9732f401384078ff1148df15525119fb6493b3aa83654455e63254344cefdff7e2d0572ebf2b
+  metadata.gz: 5483b777f81c28e3e367f84d0e4a3413b8f7d60ff09036d6148a3e565a5287252660e0fcc2aa3e7cce6c0d2f607f7a4834514f7f4da66445c1a6728ebc1a0ff6
+  data.tar.gz: b2650d632171a42556aab7d6df09d5b6c79e7cfd1a032b9806a5d49b65892c3c62435d22463a24d382904df03c02b81eb3e93d5f86b0b83570e5ff24f9bb88a8

data/lib/chat_sdk/adapter/base.rb

@@ -31,6 +31,16 @@ module ChatSDK
         raise NotImplementedError
       end
 
+      def reply_message(channel_id:, message_id:, message:, thread_id: nil)
+        require_capability!(:replies)
+        raise NotImplementedError
+      end
+
+      def mark_as_read(channel_id:, message_id:, thread_id: nil, message: nil)
+        require_capability!(:read_receipts)
+        raise NotImplementedError
+      end
+
       def edit_message(channel_id:, message_id:, message:)
         require_capability!(:edit_messages)
         raise NotImplementedError
@@ -71,6 +81,16 @@ module ChatSDK
         raise NotImplementedError
       end
 
+      def fetch_channel_messages(channel_id:, cursor: nil, limit: 50)
+        require_capability!(:message_history)
+        fetch_messages(channel_id: channel_id, cursor: cursor, limit: limit)
+      end
+
+      def list_threads(channel_id:, cursor: nil, limit: 50)
+        require_capability!(:threads)
+        raise NotImplementedError
+      end
+
       def open_modal(trigger_id:, modal:)
         require_capability!(:modals)
         raise NotImplementedError

data/lib/chat_sdk/adapter/capabilities.rb

@@ -7,7 +7,7 @@ module ChatSDK
         edit_messages delete_messages ephemeral_messages
         file_uploads reactions modals typing_indicator
         streaming_edit threads direct_messages
-        scheduled_messages message_history
+        scheduled_messages message_history replies read_receipts
       ].freeze
 
       def self.included(base)

data/lib/chat_sdk/ai/conversation_scope.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module AI
+    module ConversationScope
+      THREAD_KEY = :chat_sdk_ai_conversation_scope
+
+      class << self
+        def current
+          ::Thread.current[THREAD_KEY]
+        end
+
+        def with(thread)
+          previous = current
+          ::Thread.current[THREAD_KEY] = scope_for(thread)
+          yield
+        ensure
+          ::Thread.current[THREAD_KEY] = previous
+        end
+
+        def scope_for(value)
+          return if value.nil?
+          return value.transform_keys(&:to_sym) if value.is_a?(Hash)
+
+          {
+            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
+          }
+        end
+      end
+    end
+  end
+end

data/lib/chat_sdk/ai/converter.rb

@@ -10,7 +10,7 @@ module ChatSDK
         def to_ai_messages(messages, include_names: false, &transform)
           messages
             .sort_by { |m| m.timestamp || m.id }
-            .reject { |m| m.text.nil? || m.text.strip.empty? }
+            .reject { |m| blank_message?(m) }
             .filter_map { |m| convert_message(m, include_names: include_names, &transform) }
         end
 
@@ -19,16 +19,22 @@ module ChatSDK
         def convert_message(message, include_names: false)
           role = message.author&.bot? ? ROLE_ASSISTANT : ROLE_USER
 
-          content = message.text
+          content = message.text.to_s
           if include_names && role == ROLE_USER && message.author
             content = "[#{message.author.name}]: #{content}"
           end
 
           result = {role: role, content: content}
 
-          if message.attachments&.any?
-            parts = [{type: "text", text: content}]
-            message.attachments.each do |att|
+          if message.attachments&.any? || message.links&.any?
+            parts = []
+            parts << {type: "text", text: content} unless content.strip.empty?
+            Array(message.links).each do |link|
+              url = link.is_a?(Hash) ? (link[:url] || link["url"]) : link.to_s
+              title = link.is_a?(Hash) ? (link[:title] || link["title"]) : nil
+              parts << {type: "text", text: title ? "[#{title}](#{url})" : url}
+            end
+            Array(message.attachments).each do |att|
               parts << attachment_to_part(att)
             end
             result[:content] = parts
@@ -38,6 +44,11 @@ module ChatSDK
           result
         end
 
+        def blank_message?(message)
+          text_blank = message.text.nil? || message.text.strip.empty?
+          text_blank && !message.attachments&.any? && !message.links&.any?
+        end
+
         def attachment_to_part(attachment)
           if attachment.is_a?(Hash)
             mime = attachment[:mime_type] || attachment[:content_type] || "application/octet-stream"

data/lib/chat_sdk/ai/tool_builder.rb

@@ -72,6 +72,7 @@ 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)"},
               message_id: {type: "string", description: "Message ID to edit"},
               text: {type: "string", description: "New message text"}
             },
@@ -86,6 +87,7 @@ 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)"},
               message_id: {type: "string", description: "Message ID to delete"}
             },
             required: %w[adapter_name channel_id message_id]
@@ -99,6 +101,7 @@ 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)"},
               message_id: {type: "string", description: "Message ID"},
               emoji: {type: "string", description: "Emoji name (e.g., 'thumbsup')"}
             },
@@ -113,6 +116,7 @@ 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)"},
               message_id: {type: "string", description: "Message ID"},
               emoji: {type: "string", description: "Emoji name"}
             },
@@ -145,10 +149,21 @@ module ChatSDK
         tool_names = PRESETS[@preset]
         tool_names.each_with_object({}) do |name, tools|
           defn = TOOL_DEFINITIONS[name].dup
-          defn[:requires_approval] = @require_approval && !defn[:read_only]
+          defn[:requires_approval] = approval_required?(name, defn)
           tools[name] = defn
         end
       end
+
+      private
+
+      def approval_required?(name, definition)
+        return false if definition[:read_only] || @require_approval == false
+        return true unless @require_approval.is_a?(Hash)
+
+        @require_approval.fetch(name) do
+          @require_approval.fetch(name.to_s, true)
+        end
+      end
     end
   end
 end

data/lib/chat_sdk/ai/tool_executor.rb

@@ -3,8 +3,15 @@
 module ChatSDK
   module AI
     class ToolExecutor
-      def initialize(chat:)
+      def initialize(chat:, scope: nil, strict_scope: false)
         @chat = chat
+        @scope = if scope == false
+          false
+        else
+          ConversationScope.scope_for(scope) || ConversationScope.current&.dup
+        end
+        @strict_scope = strict_scope
+        @warned_unscoped = false
       end
 
       def execute(tool_name, arguments)
@@ -13,6 +20,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
 
         send(:"execute_#{tool_name}", adapter_name, args)
       end
@@ -56,25 +64,25 @@ module ChatSDK
       end
 
       def execute_edit_message(adapter_name, args)
-        thread = @chat.channel(args[:channel_id], adapter_name: adapter_name).thread(args[:channel_id])
+        thread = target_thread(adapter_name, args)
         thread.edit(args[:message_id], args[:text])
         {success: true}
       end
 
       def execute_delete_message(adapter_name, args)
-        thread = @chat.channel(args[:channel_id], adapter_name: adapter_name).thread(args[:channel_id])
+        thread = target_thread(adapter_name, args)
         thread.delete(args[:message_id])
         {success: true}
       end
 
       def execute_add_reaction(adapter_name, args)
-        thread = @chat.channel(args[:channel_id], adapter_name: adapter_name).thread(args[:channel_id])
+        thread = target_thread(adapter_name, args)
         thread.react(args[:message_id], args[:emoji])
         {success: true}
       end
 
       def execute_remove_reaction(adapter_name, args)
-        thread = @chat.channel(args[:channel_id], adapter_name: adapter_name).thread(args[:channel_id])
+        thread = target_thread(adapter_name, args)
         thread.unreact(args[:message_id], args[:emoji])
         {success: true}
       end
@@ -88,6 +96,35 @@ module ChatSDK
       def serialize_messages(messages)
         messages.map { |m| {id: m.id, text: m.text, author: m.author&.name, timestamp: m.timestamp} }
       end
+
+      def target_thread(adapter_name, args)
+        channel = @chat.channel(args[:channel_id], adapter_name: adapter_name)
+        channel.thread(args[:thread_id] || args[:channel_id])
+      end
+
+      def guard_scope!(adapter_name, args)
+        return if @scope == false
+
+        scope = @scope || ConversationScope.current
+        unless scope
+          unless @warned_unscoped
+            ChatSDK::Log.warn("AI tool ran without a conversation scope; pass scope: to create_executor to confine access")
+            @warned_unscoped = true
+          end
+          return
+        end
+
+        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
+        scope_is_channel = scope[:thread_id].nil?
+        in_scope = same_channel && (!@strict_scope || scope_is_channel || target_thread == scope[:thread_id].to_s)
+        return if in_scope
+
+        target = [adapter_name, target_channel, target_thread].compact.join(":")
+        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
     end
   end
 end

data/lib/chat_sdk/ai.rb

@@ -11,8 +11,8 @@ module ChatSDK
         ToolBuilder.new(preset: preset, require_approval: require_approval).build
       end
 
-      def create_executor(chat:)
-        ToolExecutor.new(chat: chat)
+      def create_executor(chat:, scope: nil, strict_scope: false)
+        ToolExecutor.new(chat: chat, scope: scope, strict_scope: strict_scope)
       end
     end
   end

data/lib/chat_sdk/author.rb

@@ -2,14 +2,16 @@
 
 module ChatSDK
   class Author
-    attr_reader :id, :name, :platform, :locale, :raw
+    attr_reader :id, :name, :platform, :locale, :email, :raw
 
-    def initialize(id:, name:, platform:, bot: false, locale: nil, raw: nil)
+    def initialize(id:, name:, platform:, bot: false, system: false, locale: nil, email: nil, raw: nil)
       @id = id
       @name = name
       @platform = platform
       @bot = bot
+      @system = system
       @locale = locale
+      @email = email
       @raw = raw
     end
 
@@ -17,6 +19,10 @@ module ChatSDK
       @bot
     end
 
+    def system?
+      @system
+    end
+
     def ==(other)
       other.is_a?(Author) && id == other.id && platform == other.platform
     end

data/lib/chat_sdk/cards/actions_context.rb

@@ -9,15 +9,19 @@ module ChatSDK
         @nodes = []
       end
 
-      def button(text, id:, style: nil, value: nil)
+      def button(text, id:, style: nil, value: nil, tooltip: nil)
         attrs = {text: text, id: id}
         attrs[:style] = style if style
         attrs[:value] = value if value
+        attrs[:tooltip] = tooltip if tooltip
         @nodes << Node.new(:button, attributes: attrs)
       end
 
-      def link_button(text, url:)
-        @nodes << Node.new(:link_button, attributes: {text: text, url: url})
+      def link_button(text, url:, id: nil, tooltip: nil)
+        attrs = {text: text, url: url}
+        attrs[:id] = id if id
+        attrs[:tooltip] = tooltip if tooltip
+        @nodes << Node.new(:link_button, attributes: attrs)
       end
 
       def select(id:, placeholder: nil, &block)

data/lib/chat_sdk/cards/builder.rb

@@ -3,9 +3,10 @@
 module ChatSDK
   module Cards
     class Builder
-      def initialize(title: nil, subtitle: nil, &block)
+      def initialize(title: nil, subtitle: nil, width: nil, &block)
         @title = title
         @subtitle = subtitle
+        @width = width
         @children = []
         instance_eval(&block) if block
       end
@@ -14,6 +15,7 @@ module ChatSDK
         attrs = {}
         attrs[:title] = @title if @title
         attrs[:subtitle] = @subtitle if @subtitle
+        attrs[:width] = @width if @width
         Node.new(:card, attributes: attrs, children: @children)
       end
 
@@ -47,6 +49,24 @@ module ChatSDK
         ctx.instance_eval(&block)
         @children << Node.new(:actions, children: ctx.nodes)
       end
+
+      def table(headers:, rows:, align: nil, caption: nil, page_size: nil)
+        attrs = {headers: headers, rows: rows}
+        attrs[:align] = align if align
+        attrs[:caption] = caption if caption
+        attrs[:page_size] = page_size if page_size
+        @children << Node.new(:table, attributes: attrs)
+      end
+
+      def chart(title:, type:, segments: nil, categories: nil, series: nil, x_label: nil, y_label: nil)
+        attrs = {title: title, chart_type: type}
+        attrs[:segments] = segments if segments
+        attrs[:categories] = categories if categories
+        attrs[:series] = series if series
+        attrs[:x_label] = x_label if x_label
+        attrs[:y_label] = y_label if y_label
+        @children << Node.new(:chart, attributes: attrs)
+      end
     end
   end
 end

data/lib/chat_sdk/cards/node.rb

@@ -31,11 +31,45 @@ module ChatSDK
             ["#{node.attributes[:label]}: #{node.attributes[:value]}"]
           when :button, :link_button
             [node.attributes[:text]]
+          when :table
+            table_text(node)
+          when :chart
+            chart_text(node)
           else
             collect_text(node.children)
           end
         end
       end
+
+      def table_text(node)
+        headers = Array(node.attributes[:headers]).map(&:to_s)
+        rows = Array(node.attributes[:rows]).map { |row| Array(row).map(&:to_s) }
+        lines = []
+        lines << node.attributes[:caption].to_s if node.attributes[:caption]
+        lines << headers.join(" | ") unless headers.empty?
+        lines.concat(rows.map { |row| row.join(" | ") })
+        lines
+      end
+
+      def chart_text(node)
+        lines = [node.attributes[:title].to_s]
+        if node.attributes[:chart_type].to_sym == :pie
+          lines.concat(Array(node.attributes[:segments]).map do |segment|
+            "#{value_for(segment, :label)}: #{value_for(segment, :value)}"
+          end)
+        else
+          Array(node.attributes[:series]).each do |series|
+            data = value_for(series, :data) || []
+            points = data.map { |point| "#{value_for(point, :label)}=#{value_for(point, :value)}" }
+            lines << "#{value_for(series, :name)}: #{points.join(", ")}"
+          end
+        end
+        lines
+      end
+
+      def value_for(hash, key)
+        hash[key] || hash[key.to_s]
+      end
     end
   end
 end

data/lib/chat_sdk/cards/renderer.rb

@@ -16,6 +16,8 @@ module ChatSDK
         when :button then "[#{node.attributes[:text]}]"
         when :link_button then "[#{node.attributes[:text]}](#{node.attributes[:url]})"
         when :select then "_#{node.attributes[:placeholder] || "Select"}_"
+        when :table then render_table(node)
+        when :chart then render_chart(node)
         else ""
         end
       end
@@ -44,6 +46,23 @@ module ChatSDK
       def render_actions(node)
         node.children.map { |c| render(c) }.join(" | ")
       end
+
+      def render_table(node)
+        headers = Array(node.attributes[:headers]).map(&:to_s)
+        rows = Array(node.attributes[:rows]).map { |row| Array(row).map(&:to_s) }
+        parts = []
+        parts << node.attributes[:caption].to_s if node.attributes[:caption]
+        unless headers.empty?
+          parts << "| #{headers.join(" | ")} |"
+          parts << "| #{headers.map { "---" }.join(" | ")} |"
+        end
+        parts.concat(rows.map { |row| "| #{row.join(" | ")} |" })
+        parts.join("\n")
+      end
+
+      def render_chart(node)
+        node.fallback_text
+      end
     end
   end
 end

data/lib/chat_sdk/channel.rb

@@ -19,6 +19,14 @@ module ChatSDK
       ChatSDK::Thread.new(id: thread_id, channel_id: id, adapter: adapter, chat: chat)
     end
 
+    def messages(cursor: nil, limit: 50)
+      adapter.fetch_channel_messages(channel_id: id, cursor: cursor, limit: limit)
+    end
+
+    def threads(cursor: nil, limit: 50)
+      adapter.list_threads(channel_id: id, cursor: cursor, limit: limit)
+    end
+
     def ==(other)
       other.is_a?(Channel) && id == other.id
     end

data/lib/chat_sdk/chat.rb

@@ -2,13 +2,14 @@
 
 module ChatSDK
   class Chat
-    attr_reader :config, :state
+    attr_reader :config, :state, :history
 
     def initialize(user_name:, adapters:, state:, **options)
       @config = Config.new(user_name: user_name, adapters: adapters, state: state, **options)
       @state = state
       @adapters = adapters
       @registry = EventRegistry.new
+      @history = History.new(self)
       @webhooks = {}
       @dispatcher = Dispatcher.new(chat: self, config: @config, state: @state, registry: @registry)
 
@@ -32,6 +33,14 @@ module ChatSDK
       @registry.register(:direct_message, &block)
     end
 
+    def on_message_updated(&block)
+      @registry.register(:message_updated, &block)
+    end
+
+    def on_message_deleted(&block)
+      @registry.register(:message_deleted, &block)
+    end
+
     def on_reaction(emojis = nil, &block)
       @registry.register(:reaction, matcher: emojis, &block)
     end
@@ -61,6 +70,11 @@ module ChatSDK
       Channel.new(id: channel_id, adapter: adp, chat: self)
     end
 
+    def thread(id, channel_id:, adapter_name: nil)
+      adp = adapter_name ? adapter(adapter_name) : @adapters.values.first
+      Thread.new(id: id, channel_id: channel_id, adapter: adp, chat: self)
+    end
+
     # Webhook endpoints (Rack apps)
     def webhooks
       @webhook_accessor ||= WebhookAccessor.new(self, @adapters)
@@ -72,6 +86,11 @@ module ChatSDK
       @dispatcher.dispatch(event, adapter: adp, adapter_name: adapter_name)
     end
 
+    # Deprecated compatibility alias for Vercel Chat SDK's former API.
+    def transcripts
+      history.user
+    end
+
     private
   end
 

data/lib/chat_sdk/config.rb

@@ -6,12 +6,16 @@ module ChatSDK
       dedupe_ttl: 600,
       streaming_update_interval: 0.5,
       on_lock_conflict: :drop,
+      concurrency: nil,
+      lock_scope: :thread,
       handler_executor: :inline,
+      history: {},
       log_level: :info
     }.freeze
 
     attr_reader :user_name, :adapters, :state, :on_lock_conflict,
-      :dedupe_ttl, :streaming_update_interval, :handler_executor, :log_level
+      :dedupe_ttl, :streaming_update_interval, :handler_executor, :log_level,
+      :history_user, :concurrency
 
     def initialize(user_name:, adapters:, state:, **options)
       raise ConfigurationError, "user_name is required" if user_name.nil? || user_name.empty?
@@ -23,9 +27,17 @@ module ChatSDK
       @state = state
       merged = DEFAULTS.merge(options)
       @on_lock_conflict = merged[:on_lock_conflict]
+      @concurrency = normalize_concurrency(merged[:concurrency], lock_scope: merged[:lock_scope])
       @dedupe_ttl = merged[:dedupe_ttl]
       @streaming_update_interval = merged[:streaming_update_interval]
       @handler_executor = merged[:handler_executor]
+      history = merged[:history] || {}
+      user_history = history[:user] || history["user"] || {}
+      @history_user = {
+        identity: user_history[:identity] || user_history["identity"] || merged[:identity],
+        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]
 
       validate_lock_conflict!
@@ -37,5 +49,40 @@ module ChatSDK
       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"
     end
+
+    def normalize_concurrency(value, lock_scope:)
+      supplied = if value.nil?
+        {}
+      elsif value.is_a?(Hash)
+        value
+      else
+        {strategy: value}
+      end
+      supplied = supplied.transform_keys(&:to_sym)
+      supplied[:debounce] = supplied.delete(:debounce_ms).to_f / 1000 if supplied.key?(:debounce_ms)
+      supplied[:queue_entry_ttl] = supplied.delete(:queue_entry_ttl_ms).to_f / 1000 if supplied.key?(:queue_entry_ttl_ms)
+      supplied[:max_lock_lifetime] = supplied.delete(:max_lock_lifetime_ms).to_f / 1000 if supplied.key?(:max_lock_lifetime_ms)
+      supplied[:lock_ttl] = supplied.delete(:lock_ttl_ms).to_f / 1000 if supplied.key?(:lock_ttl_ms)
+      config = {
+        strategy: :drop,
+        max_queue_size: 10,
+        on_queue_full: :drop_oldest,
+        queue_entry_ttl: 90,
+        debounce: 1.5,
+        lock_ttl: 30,
+        max_lock_lifetime: 600,
+        max_concurrent: nil,
+        lock_scope: lock_scope
+      }.merge(supplied)
+      config[:strategy] = config[:strategy].to_sym
+      config[:on_queue_full] = config[:on_queue_full].to_s.tr("-", "_").to_sym
+      unless %i[drop force queue burst debounce concurrent].include?(config[:strategy])
+        raise ConfigurationError, "concurrency strategy must be :drop, :queue, :burst, :debounce, or :concurrent"
+      end
+      if config[:max_concurrent] && config[:max_concurrent].to_i < 1
+        raise ConfigurationError, "max_concurrent must be at least 1"
+      end
+      config
+    end
   end
 end