chat_sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6bcc60c6b4443d14e0afb167cc7a6b8f5bbe60663fd97e275f87435313cf0705
+  data.tar.gz: 4f3820e9f8ae54789a15b89f351e035b942d741d7670accd509adf86e693b4c8
+SHA512:
+  metadata.gz: b60a52d3a1c878b74e57e57ee3ed2b40191f60ce2db45c3c80ec762324f54b738f6d4ea448f362f02f3e0a84026656e55090c1feef4abf96cfe6b67ba2c19675
+  data.tar.gz: f13771e3df25d44835659b04d424b6410eb2c9f8ffd5a53e3aaa24cd111446ca10b53a6f88adccccb6b261a7289597f0ee7c166795b6abb6fe69fccfc2fa7c4d

data/lib/chat_sdk/adapter/base.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Adapter
+    class Base
+      include Capabilities
+
+      def name
+        raise NotImplementedError
+      end
+
+      def client
+        raise NotImplementedError
+      end
+
+      # Inbound
+      def verify_request!(rack_request)
+        raise NotImplementedError
+      end
+
+      def ack_response(rack_request)
+        nil
+      end
+
+      def parse_events(rack_request)
+        raise NotImplementedError
+      end
+
+      # Outbound
+      def post_message(channel_id:, message:, thread_id: nil)
+        raise NotImplementedError
+      end
+
+      def edit_message(channel_id:, message_id:, message:)
+        require_capability!(:edit_messages)
+        raise NotImplementedError
+      end
+
+      def delete_message(channel_id:, message_id:)
+        require_capability!(:delete_messages)
+        raise NotImplementedError
+      end
+
+      def post_ephemeral(channel_id:, user_id:, message:, thread_id: nil)
+        require_capability!(:ephemeral_messages)
+        raise NotImplementedError
+      end
+
+      def upload_file(channel_id:, io:, filename:, thread_id: nil, comment: nil)
+        require_capability!(:file_uploads)
+        raise NotImplementedError
+      end
+
+      def add_reaction(channel_id:, message_id:, emoji:)
+        require_capability!(:reactions)
+        raise NotImplementedError
+      end
+
+      def remove_reaction(channel_id:, message_id:, emoji:)
+        require_capability!(:reactions)
+        raise NotImplementedError
+      end
+
+      def open_dm(user_id)
+        require_capability!(:direct_messages)
+        raise NotImplementedError
+      end
+
+      def fetch_messages(channel_id:, thread_id: nil, cursor: nil, limit: 50)
+        require_capability!(:message_history)
+        raise NotImplementedError
+      end
+
+      def open_modal(trigger_id:, modal:)
+        require_capability!(:modals)
+        raise NotImplementedError
+      end
+
+      def start_typing(channel_id:, thread_id: nil)
+        require_capability!(:typing_indicator)
+        raise NotImplementedError
+      end
+
+      def mention(user_id)
+        raise NotImplementedError
+      end
+
+      def render(postable_message)
+        Cards::Renderer.new.render(postable_message.card)
+      end
+
+      private
+
+      def require_capability!(cap)
+        raise NotSupportedError.new(cap, name) unless supports?(cap)
+      end
+    end
+  end
+end

data/lib/chat_sdk/adapter/capabilities.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Adapter
+    module Capabilities
+      KNOWN = %i[
+        edit_messages delete_messages ephemeral_messages
+        file_uploads reactions modals typing_indicator
+        streaming_edit threads direct_messages
+        scheduled_messages message_history
+      ].freeze
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def capabilities(*caps)
+          unknown = caps - KNOWN
+          raise ArgumentError, "Unknown capabilities: #{unknown.join(", ")}" if unknown.any?
+          @capabilities = caps
+        end
+
+        def declared_capabilities
+          @capabilities || []
+        end
+      end
+
+      def supports?(capability)
+        self.class.declared_capabilities.include?(capability)
+      end
+    end
+  end
+end

data/lib/chat_sdk/author.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  class Author
+    attr_reader :id, :name, :platform, :raw
+
+    def initialize(id:, name:, platform:, bot: false, raw: nil)
+      @id = id
+      @name = name
+      @platform = platform
+      @bot = bot
+      @raw = raw
+    end
+
+    def bot?
+      @bot
+    end
+
+    def ==(other)
+      other.is_a?(Author) && id == other.id && platform == other.platform
+    end
+    alias_method :eql?, :==
+
+    def hash
+      [id, platform].hash
+    end
+  end
+end

data/lib/chat_sdk/cards/actions_context.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Cards
+    class ActionsContext
+      attr_reader :nodes
+
+      def initialize
+        @nodes = []
+      end
+
+      def button(text, id:, style: nil, value: nil)
+        attrs = {text: text, id: id}
+        attrs[:style] = style if style
+        attrs[:value] = value if value
+        @nodes << Node.new(:button, attributes: attrs)
+      end
+
+      def link_button(text, url:)
+        @nodes << Node.new(:link_button, attributes: {text: text, url: url})
+      end
+
+      def select(id:, placeholder: nil, &block)
+        ctx = SelectContext.new
+        ctx.instance_eval(&block)
+        attrs = {id: id}
+        attrs[:placeholder] = placeholder if placeholder
+        @nodes << Node.new(:select, attributes: attrs, children: ctx.nodes)
+      end
+    end
+  end
+end

data/lib/chat_sdk/cards/builder.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Cards
+    class Builder
+      def initialize(title: nil, subtitle: nil, &block)
+        @title = title
+        @subtitle = subtitle
+        @children = []
+        instance_eval(&block) if block
+      end
+
+      def build
+        attrs = {}
+        attrs[:title] = @title if @title
+        attrs[:subtitle] = @subtitle if @subtitle
+        Node.new(:card, attributes: attrs, children: @children)
+      end
+
+      def text(content)
+        @children << Node.new(:text, attributes: {content: content})
+      end
+
+      def divider
+        @children << Node.new(:divider)
+      end
+
+      def image(url:, alt: nil)
+        @children << Node.new(:image, attributes: {url: url, alt: alt})
+      end
+
+      def fields(&block)
+        ctx = FieldsContext.new
+        ctx.instance_eval(&block)
+        @children << Node.new(:fields, children: ctx.nodes)
+      end
+
+      def section(title = nil, &block)
+        ctx = Builder.new
+        ctx.instance_eval(&block)
+        attrs = title ? {title: title} : {}
+        @children << Node.new(:section, attributes: attrs, children: ctx.build.children)
+      end
+
+      def actions(&block)
+        ctx = ActionsContext.new
+        ctx.instance_eval(&block)
+        @children << Node.new(:actions, children: ctx.nodes)
+      end
+    end
+  end
+end

data/lib/chat_sdk/cards/fields_context.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Cards
+    class FieldsContext
+      attr_reader :nodes
+
+      def initialize
+        @nodes = []
+      end
+
+      def field(label, value)
+        @nodes << Node.new(:field, attributes: {label: label, value: value})
+      end
+    end
+  end
+end

data/lib/chat_sdk/cards/node.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Cards
+    class Node
+      attr_reader :type, :attributes, :children
+
+      def initialize(type, attributes: {}, children: [])
+        @type = type
+        @attributes = attributes
+        @children = children.freeze
+      end
+
+      def fallback_text
+        collect_text.join("\n").strip
+      end
+
+      def ==(other)
+        other.is_a?(Node) && type == other.type &&
+          attributes == other.attributes && children == other.children
+      end
+
+      private
+
+      def collect_text(nodes = [self])
+        nodes.flat_map do |node|
+          case node.type
+          when :card
+            collect_text(node.children)
+          when :text
+            [node.attributes[:content]]
+          when :field
+            ["#{node.attributes[:label]}: #{node.attributes[:value]}"]
+          when :section
+            collect_text(node.children)
+          when :button, :link_button
+            [node.attributes[:text]]
+          else
+            collect_text(node.children)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chat_sdk/cards/renderer.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Cards
+    class Renderer
+      def render(node)
+        case node.type
+        when :card then render_card(node)
+        when :text then node.attributes[:content]
+        when :divider then "---"
+        when :image then "![#{node.attributes[:alt]}](#{node.attributes[:url]})"
+        when :fields then render_fields(node)
+        when :field then "**#{node.attributes[:label]}**: #{node.attributes[:value]}"
+        when :section then render_section(node)
+        when :actions then render_actions(node)
+        when :button then "[#{node.attributes[:text]}]"
+        when :link_button then "[#{node.attributes[:text]}](#{node.attributes[:url]})"
+        when :select then "_#{node.attributes[:placeholder] || "Select"}_"
+        else ""
+        end
+      end
+
+      private
+
+      def render_card(node)
+        parts = []
+        parts << "**#{node.attributes[:title]}**" if node.attributes[:title]
+        parts << "*#{node.attributes[:subtitle]}*" if node.attributes[:subtitle]
+        parts.concat(node.children.map { |c| render(c) })
+        parts.reject(&:empty?).join("\n\n")
+      end
+
+      def render_fields(node)
+        node.children.map { |c| render(c) }.join(" | ")
+      end
+
+      def render_section(node)
+        parts = []
+        parts << "### #{node.attributes[:title]}" if node.attributes[:title]
+        parts.concat(node.children.map { |c| render(c) })
+        parts.join("\n")
+      end
+
+      def render_actions(node)
+        node.children.map { |c| render(c) }.join(" | ")
+      end
+    end
+  end
+end

data/lib/chat_sdk/cards/select_context.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Cards
+    class SelectContext
+      attr_reader :nodes
+
+      def initialize
+        @nodes = []
+      end
+
+      def option(text, value:, description: nil)
+        attrs = {text: text, value: value}
+        attrs[:description] = description if description
+        @nodes << Node.new(:option, attributes: attrs)
+      end
+    end
+  end
+end

data/lib/chat_sdk/channel.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  class Channel
+    attr_reader :id, :adapter, :chat
+
+    def initialize(id:, adapter:, chat:)
+      @id = id
+      @adapter = adapter
+      @chat = chat
+    end
+
+    def post(content)
+      message = PostableMessage.from(content)
+      adapter.post_message(channel_id: id, message: message)
+    end
+
+    def thread(thread_id)
+      ChatSDK::Thread.new(id: thread_id, channel_id: id, adapter: adapter, chat: chat)
+    end
+
+    def ==(other)
+      other.is_a?(Channel) && id == other.id
+    end
+    alias_method :eql?, :==
+
+    def hash
+      id.hash
+    end
+  end
+end

data/lib/chat_sdk/chat.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  class Chat
+    attr_reader :config, :state
+
+    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
+      @webhooks = {}
+      @dispatcher = Dispatcher.new(chat: self, config: @config, state: @state, registry: @registry)
+
+      ChatSDK::Log.level = @config.log_level
+    end
+
+    # Event registration
+    def on_new_mention(&block)
+      @registry.register(:mention, &block)
+    end
+
+    def on_subscribed_message(&block)
+      @registry.register(:subscribed_message, &block)
+    end
+
+    def on_new_message(pattern = nil, &block)
+      @registry.register(:mention, matcher: pattern, &block)
+    end
+
+    def on_direct_message(&block)
+      @registry.register(:direct_message, &block)
+    end
+
+    def on_reaction(emojis = nil, &block)
+      @registry.register(:reaction, matcher: emojis, &block)
+    end
+
+    def on_action(action_id, &block)
+      @registry.register(:action, matcher: action_id, &block)
+    end
+
+    def on_slash_command(command, &block)
+      @registry.register(:slash_command, matcher: command, &block)
+    end
+
+    # Adapter access
+    def adapter(name)
+      @adapters.fetch(name) { raise ChatSDK::ConfigurationError, "Unknown adapter: #{name}" }
+    end
+
+    # Channel/DM access
+    def channel(id, adapter_name: nil)
+      adp = adapter_name ? adapter(adapter_name) : @adapters.values.first
+      Channel.new(id: id, adapter: adp, chat: self)
+    end
+
+    def open_dm(user_id, adapter_name: nil)
+      adp = adapter_name ? adapter(adapter_name) : @adapters.values.first
+      channel_id = adp.open_dm(user_id)
+      Channel.new(id: channel_id, adapter: adp, chat: self)
+    end
+
+    # Webhook endpoints (Rack apps)
+    def webhooks
+      @webhook_accessor ||= WebhookAccessor.new(self, @adapters)
+    end
+
+    # Event dispatch (called by webhook endpoints)
+    def dispatch(event, adapter_name:)
+      adp = adapter(adapter_name)
+      @dispatcher.dispatch(event, adapter: adp, adapter_name: adapter_name)
+    end
+
+    private
+  end
+
+  class WebhookAccessor
+    def initialize(chat, adapters)
+      @chat = chat
+      @adapters = adapters
+      @endpoints = {}
+    end
+
+    def [](adapter_name)
+      @endpoints[adapter_name] ||= Webhook::Endpoint.new(chat: @chat, adapter: @chat.adapter(adapter_name), adapter_name: adapter_name)
+    end
+
+    def router
+      @router ||= Webhook::Router.new(@chat, @adapters)
+    end
+  end
+end

data/lib/chat_sdk/config.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  class Config
+    DEFAULTS = {
+      dedupe_ttl: 600,
+      streaming_update_interval: 0.5,
+      on_lock_conflict: :drop,
+      handler_executor: :inline,
+      log_level: :info
+    }.freeze
+
+    attr_reader :user_name, :adapters, :state, :on_lock_conflict,
+      :dedupe_ttl, :streaming_update_interval, :handler_executor, :log_level
+
+    def initialize(user_name:, adapters:, state:, **options)
+      raise ConfigurationError, "user_name is required" if user_name.nil? || user_name.empty?
+      raise ConfigurationError, "adapters hash is required" if adapters.nil? || adapters.empty?
+      raise ConfigurationError, "state adapter is required" if state.nil?
+
+      @user_name = user_name
+      @adapters = adapters
+      @state = state
+      merged = DEFAULTS.merge(options)
+      @on_lock_conflict = merged[:on_lock_conflict]
+      @dedupe_ttl = merged[:dedupe_ttl]
+      @streaming_update_interval = merged[:streaming_update_interval]
+      @handler_executor = merged[:handler_executor]
+      @log_level = merged[:log_level]
+
+      validate_lock_conflict!
+    end
+
+    private
+
+    def validate_lock_conflict!
+      return if %i[drop force].include?(@on_lock_conflict) || @on_lock_conflict.respond_to?(:call)
+      raise ConfigurationError, "on_lock_conflict must be :drop, :force, or a callable"
+    end
+  end
+end

data/lib/chat_sdk/dispatcher.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  class Dispatcher
+    def initialize(chat:, config:, state:, registry:)
+      @chat = chat
+      @config = config
+      @state = state
+      @registry = registry
+    end
+
+    def dispatch(event, adapter:, adapter_name:)
+      return unless dedupe(event, adapter_name)
+
+      thread = build_thread(event, adapter)
+      thread_key = thread_key_for(event, adapter_name)
+
+      return unless acquire_lock(thread_key, event)
+
+      begin
+        handlers = @registry.handlers_for(event)
+        handlers.each { |handler| execute_handler(handler, event, thread) }
+      ensure
+        release_lock(thread_key)
+      end
+    end
+
+    private
+
+    def dedupe(event, adapter_name)
+      event_id = extract_event_id(event)
+      return true unless event_id
+
+      @state.set_if_absent(
+        "chat_sdk:dedupe:#{adapter_name}:#{event_id}",
+        true,
+        ttl: @config.dedupe_ttl
+      )
+    end
+
+    def extract_event_id(event)
+      if event.respond_to?(:message) && event.message
+        event.message.id
+      elsif event.respond_to?(:raw) && event.raw.is_a?(Hash)
+        event.raw[:event_id] || event.raw["event_id"]
+      end
+    end
+
+    def thread_key_for(event, adapter_name)
+      channel_id = event.respond_to?(:channel_id) ? event.channel_id : nil
+      thread_id = event.respond_to?(:thread_id) ? event.thread_id : nil
+      "#{adapter_name}:#{channel_id}:#{thread_id}"
+    end
+
+    def lock_owner
+      @lock_owner ||= "#{Process.pid}:#{::Thread.current.object_id}"
+    end
+
+    def acquire_lock(thread_key, event)
+      lock_key = "chat_sdk:lock:#{thread_key}"
+      return true if @state.acquire_lock(lock_key, owner: lock_owner, ttl: 30)
+
+      case @config.on_lock_conflict
+      when :drop
+        ChatSDK::Log.debug("Lock conflict, dropping event for #{thread_key}")
+        false
+      when :force
+        @state.force_lock(lock_key, owner: lock_owner, ttl: 30)
+        true
+      else
+        if @config.on_lock_conflict.respond_to?(:call)
+          policy = @config.on_lock_conflict.call(thread_key, event)
+          case policy
+          when :force
+            @state.force_lock(lock_key, owner: lock_owner, ttl: 30)
+            true
+          else
+            false
+          end
+        else
+          false
+        end
+      end
+    end
+
+    def release_lock(thread_key)
+      @state.release_lock("chat_sdk:lock:#{thread_key}", owner: lock_owner)
+    end
+
+    def build_thread(event, adapter)
+      thread_id = event.respond_to?(:thread_id) ? event.thread_id : nil
+      channel_id = event.respond_to?(:channel_id) ? event.channel_id : nil
+      return nil unless thread_id && channel_id
+
+      ChatSDK::Thread.new(id: thread_id, channel_id: channel_id, adapter: adapter, chat: @chat)
+    end
+
+    def execute_handler(handler, event, thread)
+      case event.type
+      when :mention, :subscribed_message, :direct_message
+        handler.block.call(thread, event.message)
+      when :reaction, :action, :slash_command
+        add_thread_to_event(event, thread)
+        handler.block.call(event)
+      end
+    rescue => e
+      ChatSDK::Log.error("Handler error (#{event.type}): #{e.message}")
+      ChatSDK::Log.debug(e.backtrace&.first(5)&.join("\n"))
+    end
+
+    def add_thread_to_event(event, thread)
+      event.instance_variable_set(:@thread, thread)
+      unless event.respond_to?(:thread)
+        event.define_singleton_method(:thread) { @thread }
+      end
+    end
+  end
+end