chat_sdk-telegram 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9c91f00043b554f53ef31b9c1c73540d7495ed60313802c7f4db3f8e41f6729e
+  data.tar.gz: 9f081cdebba34e0ecfad397fc72d031770b8ce92ae2cdd0c6c694a3216e7af31
+SHA512:
+  metadata.gz: 7e9b5f9eab5c771f56fab8e708d26ffe14a56415add30a4aab5a9b04a61ffc5f64284358c8e8ccf913bb28525e1ccf183352159eb7111572912737c8f0dadf9a
+  data.tar.gz: 5da8589bb74c1279e6adc239e385aab47fe4e36536b7cd2030e00b443891a9af799f6b7fe883f10459a72a5f7a4df316acd262279e50dcb72a5b054b7d796037

data/lib/chat_sdk/telegram/adapter.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "rack/utils"
+
+module ChatSDK
+  module Telegram
+    class Adapter < ChatSDK::Adapter::Base
+      capabilities :edit_messages, :delete_messages, :reactions, :file_uploads,
+        :typing_indicator, :streaming_edit, :direct_messages
+
+      attr_reader :client
+
+      def initialize(bot_token: nil, secret_token: nil, bot_username: nil)
+        @bot_token = bot_token || ENV["TELEGRAM_BOT_TOKEN"]
+        @secret_token = secret_token || ENV["TELEGRAM_WEBHOOK_SECRET_TOKEN"]
+        @bot_username = bot_username || ENV["TELEGRAM_BOT_USERNAME"]
+
+        raise ChatSDK::ConfigurationError, "Telegram bot_token required" unless @bot_token
+
+        @client = ApiClient.new(@bot_token)
+        @renderer = KeyboardRenderer.new
+      end
+
+      def name
+        :telegram
+      end
+
+      # Inbound
+      def verify_request!(rack_request)
+        return true unless @secret_token
+
+        header_token = rack_request.get_header("HTTP_X_TELEGRAM_BOT_API_SECRET_TOKEN")
+
+        unless header_token
+          raise ChatSDK::SignatureVerificationError, "Missing Telegram secret token header"
+        end
+
+        unless Rack::Utils.secure_compare(header_token, @secret_token)
+          raise ChatSDK::SignatureVerificationError, "Invalid Telegram secret token"
+        end
+
+        true
+      end
+
+      def ack_response(_rack_request)
+        nil
+      end
+
+      def parse_events(rack_request)
+        body = rack_request.body.read
+        rack_request.body.rewind
+
+        payload = JSON.parse(body)
+        EventParser.parse(payload, bot_username: @bot_username)
+      rescue JSON::ParserError
+        []
+      end
+
+      # Outbound
+      def post_message(channel_id:, message:, thread_id: nil)
+        text, reply_markup = prepare_message_payload(message)
+
+        result = @client.send_message(
+          chat_id: channel_id,
+          text: text,
+          reply_markup: reply_markup,
+          reply_to_message_id: thread_id
+        )
+
+        parse_telegram_message(result, channel_id)
+      end
+
+      def edit_message(channel_id:, message_id:, message:)
+        text, reply_markup = prepare_message_payload(message)
+
+        @client.edit_message_text(
+          chat_id: channel_id,
+          message_id: message_id,
+          text: text,
+          reply_markup: reply_markup
+        )
+      end
+
+      def delete_message(channel_id:, message_id:)
+        @client.delete_message(chat_id: channel_id, message_id: message_id)
+      end
+
+      def upload_file(channel_id:, io:, filename:, thread_id: nil, comment: nil)
+        @client.send_document(
+          chat_id: channel_id,
+          document: io,
+          filename: filename,
+          caption: comment,
+          reply_to_message_id: thread_id
+        )
+      end
+
+      def add_reaction(channel_id:, message_id:, emoji:)
+        @client.set_message_reaction(
+          chat_id: channel_id,
+          message_id: message_id,
+          reaction: [{"type" => "emoji", "emoji" => emoji}]
+        )
+      end
+
+      def remove_reaction(channel_id:, message_id:, emoji:) # rubocop:disable Lint/UnusedMethodArgument
+        @client.set_message_reaction(
+          chat_id: channel_id,
+          message_id: message_id,
+          reaction: []
+        )
+      end
+
+      def open_dm(user_id)
+        user_id
+      end
+
+      def start_typing(channel_id:, thread_id: nil) # rubocop:disable Lint/UnusedMethodArgument
+        @client.send_chat_action(chat_id: channel_id, action: "typing")
+      end
+
+      def mention(user_id)
+        "[user](tg://user?id=#{user_id})"
+      end
+
+      def render(postable_message)
+        if postable_message.card?
+          @renderer.render(postable_message.card)
+        else
+          postable_message.text
+        end
+      end
+
+      private
+
+      def prepare_message_payload(message)
+        msg = ChatSDK::PostableMessage.from(message)
+        text = msg.text || msg.card&.fallback_text || ""
+        reply_markup = nil
+        if msg.card?
+          rendered = @renderer.render(msg.card)
+          text = rendered[:text] if rendered[:text] && !rendered[:text].empty?
+          reply_markup = rendered[:reply_markup]
+        end
+        [text, reply_markup]
+      end
+
+      def parse_telegram_message(data, channel_id)
+        ChatSDK::Message.new(
+          id: data["message_id"]&.to_s,
+          text: data["text"] || "",
+          author: ChatSDK::Author.new(
+            id: data.dig("from", "id")&.to_s || "bot",
+            name: data.dig("from", "username") || "bot",
+            platform: :telegram,
+            bot: true
+          ),
+          thread_id: data["message_id"]&.to_s,
+          channel_id: channel_id,
+          platform: :telegram,
+          raw: data
+        )
+      end
+    end
+  end
+end

data/lib/chat_sdk/telegram/api_client.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Telegram
+    class ApiClient
+      BASE_URL = "https://api.telegram.org"
+
+      def initialize(bot_token)
+        @bot_token = bot_token
+      end
+
+      def send_message(chat_id:, text:, reply_markup: nil, reply_to_message_id: nil)
+        body = {"chat_id" => chat_id, "text" => text, "parse_mode" => "Markdown"}
+        body["reply_markup"] = reply_markup if reply_markup
+        body["reply_to_message_id"] = reply_to_message_id if reply_to_message_id
+        request(:post, "sendMessage", body)
+      end
+
+      def edit_message_text(chat_id:, message_id:, text:, reply_markup: nil)
+        body = {"chat_id" => chat_id, "message_id" => message_id, "text" => text, "parse_mode" => "Markdown"}
+        body["reply_markup"] = reply_markup if reply_markup
+        request(:post, "editMessageText", body)
+      end
+
+      def delete_message(chat_id:, message_id:)
+        request(:post, "deleteMessage", {"chat_id" => chat_id, "message_id" => message_id})
+      end
+
+      def send_document(chat_id:, document:, filename:, caption: nil, reply_to_message_id: nil)
+        payload = {
+          "chat_id" => chat_id,
+          "document" => Faraday::Multipart::FilePart.new(document, "application/octet-stream", filename)
+        }
+        payload["caption"] = caption if caption
+        payload["reply_to_message_id"] = reply_to_message_id if reply_to_message_id
+
+        response = upload_connection.post(api_path("sendDocument"), payload)
+        handle_response(response)
+      end
+
+      def set_message_reaction(chat_id:, message_id:, reaction:)
+        request(:post, "setMessageReaction", {
+          "chat_id" => chat_id,
+          "message_id" => message_id,
+          "reaction" => reaction
+        })
+      end
+
+      def send_chat_action(chat_id:, action:)
+        request(:post, "sendChatAction", {"chat_id" => chat_id, "action" => action})
+      end
+
+      private
+
+      def api_path(method)
+        "/bot#{@bot_token}/#{method}"
+      end
+
+      def connection
+        @connection ||= Faraday.new(url: BASE_URL) do |f|
+          f.request :json
+          f.response :json
+          f.adapter :net_http
+        end
+      end
+
+      def upload_connection
+        @upload_connection ||= Faraday.new(url: BASE_URL) do |f|
+          f.request :multipart
+          f.response :json
+          f.adapter :net_http
+        end
+      end
+
+      def request(method, api_method, body = nil)
+        response = connection.public_send(method, api_path(api_method)) do |req|
+          req.body = body if body && method != :get
+        end
+
+        handle_response(response)
+      end
+
+      def handle_response(response)
+        body = response.body
+
+        if response.success? && body.is_a?(Hash) && body["ok"]
+          return body["result"]
+        end
+
+        if response.status == 429
+          retry_after = body.is_a?(Hash) ? body.dig("parameters", "retry_after")&.to_i : nil
+          raise ChatSDK::RateLimitedError.new(
+            "Telegram API rate limited",
+            retry_after: retry_after,
+            status: response.status,
+            body: body,
+            adapter_name: :telegram
+          )
+        end
+
+        description = body.is_a?(Hash) ? body["description"] : response.status
+        raise ChatSDK::PlatformError.new(
+          "Telegram API error: #{description}",
+          status: response.status,
+          body: body,
+          adapter_name: :telegram
+        )
+      end
+    end
+  end
+end

data/lib/chat_sdk/telegram/event_parser.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Telegram
+    class EventParser
+      class << self
+        def parse(payload, bot_username: nil)
+          return [] unless payload.is_a?(Hash)
+
+          if payload["callback_query"]
+            parse_callback_query(payload["callback_query"])
+          elsif payload["message"]
+            parse_message(payload["message"], bot_username: bot_username)
+          else
+            []
+          end
+        end
+
+        private
+
+        def parse_message(message, bot_username: nil)
+          return parse_bot_command(message, extract_user(message), message.dig("chat", "id")&.to_s, resolve_thread_id(message)) if bot_command?(message)
+
+          user = extract_user(message)
+          chat_id = message.dig("chat", "id")&.to_s
+          chat_type = message.dig("chat", "type")
+          text = message["text"] || ""
+          thread_id = resolve_thread_id(message)
+
+          msg = ChatSDK::Message.new(
+            id: message["message_id"]&.to_s,
+            text: text,
+            author: ChatSDK::Author.new(id: user[:id], name: user[:name], platform: :telegram, bot: false),
+            thread_id: thread_id,
+            channel_id: chat_id,
+            platform: :telegram,
+            raw: message
+          )
+
+          event_class = if mention?(text, bot_username)
+            ChatSDK::Events::Mention
+          elsif chat_type == "private"
+            ChatSDK::Events::DirectMessage
+          else
+            ChatSDK::Events::SubscribedMessage
+          end
+
+          [event_class.new(message: msg, thread_id: thread_id, channel_id: chat_id,
+            platform: :telegram, adapter_name: :telegram, raw: message)]
+        end
+
+        def parse_callback_query(callback)
+          user_info = callback["from"] || {}
+          message = callback["message"] || {}
+          chat_id = message.dig("chat", "id")&.to_s
+          message_id = message["message_id"]&.to_s
+          callback_data = callback["data"] || ""
+
+          action_id, value = callback_data.split(":", 2)
+          value ||= action_id
+
+          user = ChatSDK::Author.new(
+            id: user_info["id"]&.to_s || "unknown",
+            name: user_info["username"] || user_info["first_name"] || "unknown",
+            platform: :telegram,
+            bot: false
+          )
+
+          [ChatSDK::Events::Action.new(
+            action_id: action_id,
+            value: value,
+            user: user,
+            thread_id: message_id,
+            channel_id: chat_id,
+            platform: :telegram,
+            adapter_name: :telegram,
+            raw: callback
+          )]
+        end
+
+        def extract_user(message)
+          from = message["from"] || {}
+          {
+            id: from["id"]&.to_s || "unknown",
+            name: from["username"] || from["first_name"] || "unknown"
+          }
+        end
+
+        def resolve_thread_id(message)
+          reply = message.dig("reply_to_message", "message_id")
+          (reply || message["message_id"])&.to_s
+        end
+
+        def bot_command?(message)
+          entities = message["entities"]
+          return false unless entities.is_a?(Array)
+
+          entities.any? { |e| e["type"] == "bot_command" }
+        end
+
+        def mention?(text, bot_username)
+          return false unless bot_username
+
+          text.include?("@#{bot_username}")
+        end
+
+        def parse_bot_command(message, user, chat_id, thread_id)
+          text = message["text"] || ""
+          parts = text.split(" ", 2)
+          command = parts[0]&.split("@")&.first || ""
+          args = parts[1] || ""
+
+          [ChatSDK::Events::SlashCommand.new(
+            command: command,
+            text: args,
+            user_id: user[:id],
+            channel_id: chat_id,
+            trigger_id: message["message_id"]&.to_s,
+            platform: :telegram,
+            adapter_name: :telegram,
+            raw: message
+          )]
+        end
+      end
+    end
+  end
+end

data/lib/chat_sdk/telegram/keyboard_renderer.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module Telegram
+    class KeyboardRenderer
+      def render(node)
+        case node.type
+        when :card then render_card(node)
+        else render_single(node)
+        end
+      end
+
+      private
+
+      def render_card(node)
+        text_parts = []
+        keyboard_rows = []
+
+        text_parts << "*#{node.attributes[:title]}*" if node.attributes[:title]
+        text_parts << "_#{node.attributes[:subtitle]}_" if node.attributes[:subtitle]
+
+        node.children.each do |child|
+          case child.type
+          when :text
+            text_parts << child.attributes[:content]
+          when :divider
+            text_parts << "───"
+          when :image
+            text_parts << "[Image](#{child.attributes[:url]})"
+          when :fields
+            child.children.each do |field|
+              text_parts << "*#{field.attributes[:label]}*: #{field.attributes[:value]}"
+            end
+          when :section
+            render_section_into(child, text_parts, keyboard_rows)
+          when :actions
+            render_actions_into(child, keyboard_rows)
+          when :button
+            keyboard_rows << [render_button(child)]
+          when :link_button
+            keyboard_rows << [render_link_button(child)]
+          when :select
+            render_select_into(child, keyboard_rows)
+          end
+        end
+
+        result = {text: text_parts.join("\n")}
+        unless keyboard_rows.empty?
+          result[:reply_markup] = {"inline_keyboard" => keyboard_rows}
+        end
+        result
+      end
+
+      def render_section_into(node, text_parts, keyboard_rows)
+        text_parts << "*#{node.attributes[:title]}*" if node.attributes[:title]
+
+        node.children.each do |child|
+          case child.type
+          when :text
+            text_parts << child.attributes[:content]
+          when :fields
+            child.children.each do |field|
+              text_parts << "*#{field.attributes[:label]}*: #{field.attributes[:value]}"
+            end
+          when :actions
+            render_actions_into(child, keyboard_rows)
+          when :button
+            keyboard_rows << [render_button(child)]
+          when :link_button
+            keyboard_rows << [render_link_button(child)]
+          when :select
+            render_select_into(child, keyboard_rows)
+          end
+        end
+      end
+
+      def render_actions_into(node, keyboard_rows)
+        row = []
+        node.children.each do |child|
+          if child.type == :select
+            keyboard_rows << row unless row.empty?
+            row = []
+            render_select_into(child, keyboard_rows)
+          else
+            comp = render_component(child)
+            row << comp if comp
+          end
+        end
+        keyboard_rows << row unless row.empty?
+      end
+
+      def render_component(node)
+        case node.type
+        when :button then render_button(node)
+        when :link_button then render_link_button(node)
+        end
+      end
+
+      def render_button(node)
+        callback_data = if node.attributes[:value]
+          "#{node.attributes[:id]}:#{node.attributes[:value]}"
+        else
+          node.attributes[:id] || "button"
+        end
+
+        {"text" => node.attributes[:text], "callback_data" => callback_data}
+      end
+
+      def render_link_button(node)
+        {"text" => node.attributes[:text], "url" => node.attributes[:url]}
+      end
+
+      def render_select_into(node, keyboard_rows)
+        node.children.each do |opt|
+          callback_data = "#{node.attributes[:id]}:#{opt.attributes[:value]}"
+          keyboard_rows << [{"text" => opt.attributes[:text], "callback_data" => callback_data}]
+        end
+      end
+
+      def render_single(node)
+        case node.type
+        when :text
+          {text: node.attributes[:content]}
+        else
+          {text: node.fallback_text}
+        end
+      end
+    end
+  end
+end

data/lib/chat_sdk/telegram.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "chat_sdk"
+require "faraday"
+require "faraday/net_http"
+require "zeitwerk"
+
+module ChatSDK
+  module Telegram
+    class << self
+      def loader
+        @loader ||= begin
+          loader = Zeitwerk::Loader.new
+          loader.tag = "chat_sdk-telegram"
+          loader.inflector.inflect("chat_sdk" => "ChatSDK")
+          loader.push_dir("#{__dir__}/telegram", namespace: ChatSDK::Telegram)
+          loader.setup
+          loader
+        end
+      end
+    end
+  end
+end
+
+ChatSDK::Telegram.loader

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: chat_sdk-telegram
+version: !ruby/object:Gem::Version
+  version: 0.2.1
+platform: ruby
+authors:
+- Rootly
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: chat_sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Telegram Bot API adapter for the ChatSDK framework
+email:
+- eng@rootly.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/chat_sdk/telegram.rb
+- lib/chat_sdk/telegram/adapter.rb
+- lib/chat_sdk/telegram/api_client.rb
+- lib/chat_sdk/telegram/event_parser.rb
+- lib/chat_sdk/telegram/keyboard_renderer.rb
+homepage: https://github.com/rootlyhq/chat-sdk
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Telegram adapter for ChatSDK
+test_files: []