grammerb 0.1.0-x86_64-linux

data/lib/grammerb/client.rb

@@ -0,0 +1,802 @@
+# lib/grammerb/client.rb
+require "logger"
+require "base64"
+require "set"
+
+module Grammerb
+  class HandlerPool
+    def initialize(size)
+      @queue = Queue.new
+      @workers = size.times.map do
+        Thread.new do
+          loop do
+            task = @queue.pop
+            break if task == :shutdown
+            task.call
+          rescue => e
+            # Error handling is inside the task block itself
+          end
+        end
+      end
+    end
+
+    def schedule(&block)
+      @queue.push(block)
+    end
+
+    def shutdown
+      @workers.size.times { @queue.push(:shutdown) }
+      @workers.each { |t| t.join(5) }
+    end
+  end
+
+  class Client
+    attr_reader :native, :logger
+
+    def initialize(api_id:, api_hash:, session: "grammerb.session", proxy: nil, logger: nil, pool_size: 20)
+      @session_path = session
+      @native = Grammerb::Native::Client.new(api_id, api_hash, session, proxy)
+      @handlers = []
+      @handlers_mu = Mutex.new
+      @handlers_snapshot = [].freeze
+      @running = false
+      @running_mu = Mutex.new
+      @handler_pool = HandlerPool.new(pool_size)
+      @conversations = {}
+      @conversations_mu = Mutex.new
+      @logger = logger || default_logger
+      @entity_cache = {}
+      @entity_cache_mu = Mutex.new
+    end
+
+    # --- Connection ---
+
+    def connect
+      @logger.debug("Connecting...")
+      safe_native { @native.connect }
+      @logger.info("Connected")
+      self
+    end
+
+    def disconnect
+      @logger.info("Disconnecting...")
+      safe_native { @native.disconnect }
+    end
+
+    def authorized?
+      safe_native { @native.is_authorized }
+    end
+
+    # --- Auth ---
+
+    def start(phone:, code_callback: nil, password_callback: nil)
+      connect
+
+      return self if authorized?
+
+      safe_native { @native.request_login_code(phone) }
+
+      code = if code_callback
+               code_callback.call
+             else
+               print "Enter the code you received: "
+               $stdin.gets&.chomp || (raise Errors::AuthError, "No input available for code")
+             end
+
+      result = safe_native { @native.sign_in(code) }
+
+      case result
+      when "ok"
+        # Signed in successfully
+      when "2fa_required"
+        password = if password_callback
+                     password_callback.call
+                   else
+                     print "Enter your 2FA password: "
+                     $stdin.gets&.chomp || (raise Errors::AuthError, "No input available for password")
+                   end
+        safe_native { @native.check_password(password) }
+      when "sign_up_required"
+        raise Errors::AuthError, "This phone number is not registered with Telegram"
+      end
+
+      self
+    end
+
+    def bot_start(token:)
+      connect
+      unless authorized?
+        safe_native { @native.bot_sign_in(token) }
+      end
+      self
+    end
+
+    def sign_out
+      safe_native { @native.sign_out }
+    end
+
+    # --- Messages ---
+
+    def send_message(chat, text, reply_to: nil, parse_mode: nil, silent: false, link_preview: true, schedule: nil, comment_to: nil, send_as: nil, buttons: nil, reply_markup: nil)
+      markup = reply_markup || (buttons ? build_buttons(buttons) : nil)
+      schedule_ts = schedule&.to_i
+      sa = send_as ? peer_id(send_as) : nil
+      h = safe_native { @native.send_message_advanced(peer_id(chat), text.to_s, reply_to, parse_mode, silent, link_preview, schedule_ts, comment_to, sa, markup) }
+      wrap_message(h)
+    end
+
+    def edit_message(chat, message_id, text, parse_mode: nil, link_preview: true, buttons: nil, reply_markup: nil)
+      markup = reply_markup || (buttons ? build_buttons(buttons) : nil)
+      safe_native { @native.edit_message(peer_id(chat), message_id, text.to_s, parse_mode, link_preview, markup) }
+      self
+    end
+
+    def delete_messages(chat, *message_ids, revoke: true)
+      ids = message_ids.flatten
+      safe_native { @native.delete_messages(peer_id(chat), ids, revoke) }
+    end
+
+    def forward_messages(from_chat, message_ids, to_chat, silent: false, schedule: nil, drop_author: false, noforwards: false)
+      ids = Array(message_ids)
+      schedule_ts = schedule&.to_i
+      safe_native { @native.forward_messages(peer_id(from_chat), ids, peer_id(to_chat), silent, schedule_ts, drop_author, noforwards) }.map { |h| h ? wrap_message(h) : nil }
+    end
+
+    def get_messages(chat, limit: 20, offset_id: nil, offset_date: nil)
+      ts = offset_date.is_a?(Time) ? offset_date.to_i : offset_date
+      safe_native { @native.get_messages(peer_id(chat), limit, offset_id, ts) }.map { |h| wrap_message(h) }
+    end
+
+    def get_messages_by_id(chat, *message_ids)
+      ids = message_ids.flatten
+      safe_native { @native.get_messages_by_id(peer_id(chat), ids) }.map { |h| h ? wrap_message(h) : nil }
+    end
+
+    def pin_message(chat, message_id, notify: false)
+      safe_native { @native.pin_message(peer_id(chat), message_id, notify) }
+    end
+
+    def unpin_message(chat, message_id)
+      safe_native { @native.unpin_message(peer_id(chat), message_id) }
+    end
+
+    def unpin_all_messages(chat)
+      safe_native { @native.unpin_all_messages(peer_id(chat)) }
+    end
+
+    def get_pinned_message(chat)
+      h = safe_native { @native.get_pinned_message(peer_id(chat)) }
+      h ? wrap_message(h) : nil
+    end
+
+    def send_reactions(chat, message_id, *reactions)
+      emojis = reactions.flatten
+      safe_native { @native.send_reactions(peer_id(chat), message_id, emojis) }
+    end
+
+    def search_messages(chat, query: "", limit: 100, filter: nil, from_user: nil)
+      fu = from_user ? peer_id(from_user) : nil
+      safe_native { @native.search_messages(peer_id(chat), query, limit, filter, fu) }.map { |h| wrap_message(h) }
+    end
+
+    def search_all_messages(query: "", limit: 100)
+      safe_native { @native.search_all_messages(query, limit) }.map { |h| wrap_message(h) }
+    end
+
+    def get_reply_to_message(chat, message_id)
+      h = safe_native { @native.get_reply_to_message(peer_id(chat), message_id) }
+      h ? wrap_message(h) : nil
+    end
+
+    def send_chat_action(chat, action)
+      safe_native { @native.send_chat_action(peer_id(chat), action.to_s) }
+    end
+
+    def send_poll(chat, question, answers, quiz: false, correct_option: nil)
+      h = safe_native { @native.send_poll(peer_id(chat), question.to_s, Array(answers), quiz, correct_option) }
+      wrap_message(h)
+    end
+
+    def get_poll_results(chat, message_id)
+      h = safe_native { @native.get_poll_results(peer_id(chat), message_id) }
+      Types::PollResults.new(h)
+    end
+
+    def get_poll_votes(chat, message_id, option: nil, limit: 100)
+      h = safe_native { @native.get_poll_votes(peer_id(chat), message_id, option, limit) }
+      Types::PollVotes.new(h)
+    end
+
+    # --- Dialogs ---
+
+    def iter_dialogs(limit: 100)
+      safe_native { @native.iter_dialogs(limit) }.map { |h| Types::Dialog.new(h) }
+    end
+    alias_method :get_dialogs, :iter_dialogs
+
+    def delete_dialog(chat)
+      safe_native { @native.delete_dialog(peer_id(chat)) }
+    end
+
+    def mark_as_read(chat)
+      safe_native { @native.mark_as_read(peer_id(chat)) }
+    end
+
+    def send_read_acknowledge(chat, message = nil, max_id: nil)
+      mid = max_id || (message.respond_to?(:id) ? message.id : message&.to_i) || 0
+      safe_native { @native.send_read_acknowledge(peer_id(chat), mid) }
+    end
+
+    def iter_drafts
+      safe_native { @native.iter_drafts }.map { |h| Types::Draft.new(h) }
+    end
+    alias_method :get_drafts, :iter_drafts
+
+    def clear_drafts
+      safe_native { @native.clear_all_drafts }
+    end
+
+    def clear_mentions(chat)
+      safe_native { @native.clear_mentions(peer_id(chat)) }
+    end
+
+    # --- Users / Chats ---
+
+    def get_me
+      Types::User.new(safe_native { @native.get_me })
+    end
+
+    def get_entity(entity)
+      key = peer_id(entity)
+      cached = @entity_cache_mu.synchronize { @entity_cache[key] }
+      return cached if cached
+
+      h = safe_native { @native.get_entity(key) }
+      return nil unless h
+      peer = Types::Peer.new(h)
+      @entity_cache_mu.synchronize { @entity_cache[key] = peer }
+      peer
+    end
+
+    def edit_permissions(chat, **rights)
+      rights_hash = rights.transform_keys(&:to_sym)
+      safe_native { @native.edit_permissions(peer_id(chat), rights_hash) }
+    end
+
+    def resolve_username(username)
+      normalized = username.to_s.delete_prefix("@")
+      key = "@#{normalized}"
+      cached = @entity_cache_mu.synchronize { @entity_cache[key] }
+      return cached if cached
+
+      h = safe_native { @native.resolve_username(normalized) }
+      return nil unless h
+      peer = Types::Peer.new(h)
+      @entity_cache_mu.synchronize { @entity_cache[key] = peer }
+      peer
+    end
+
+    def iter_participants(chat, limit: 200, filter: nil, search: nil, aggressive: false)
+      unless aggressive
+        return safe_native { @native.iter_participants(peer_id(chat), limit, filter, search) }.map { |h| Types::Participant.new(h) }
+      end
+
+      # Aggressive mode: query with different search strings to get all participants
+      seen = {}
+      result = []
+      # First get recent participants
+      safe_native { @native.iter_participants(peer_id(chat), limit, filter, nil) }.each do |h|
+        p = Types::Participant.new(h)
+        unless seen[p.id]
+          seen[p.id] = true
+          result << p
+        end
+      end
+      # Then search with each letter
+      ("a".."z").each do |letter|
+        break if result.size >= limit
+        safe_native { @native.iter_participants(peer_id(chat), limit, filter, letter) }.each do |h|
+          p = Types::Participant.new(h)
+          unless seen[p.id]
+            seen[p.id] = true
+            result << p
+          end
+        end
+      end
+      result.first(limit)
+    end
+    alias_method :get_participants, :iter_participants
+
+    def kick_participant(chat, user)
+      safe_native { @native.kick_participant(peer_id(chat), peer_id(user)) }
+    end
+
+    def set_admin_rights(chat, user, **rights)
+      rights_hash = rights.transform_keys(&:to_sym)
+      safe_native { @native.set_admin_rights(peer_id(chat), peer_id(user), rights_hash) }
+    end
+
+    def set_banned_rights(chat, user, **rights)
+      rights_hash = rights.transform_keys(&:to_sym)
+      safe_native { @native.set_banned_rights(peer_id(chat), peer_id(user), rights_hash) }
+    end
+
+    def get_permissions(chat, user)
+      Types::Permissions.new(safe_native { @native.get_permissions(peer_id(chat), peer_id(user)) })
+    end
+
+    def iter_profile_photos(chat, limit: 100)
+      safe_native { @native.iter_profile_photos(peer_id(chat), limit) }
+    end
+
+    def join_chat(chat)
+      link = chat.to_s
+      if link.match?(%r{(t\.me|telegram\.me|telegram\.dog)/(\+|joinchat/)}) || link.match?(%r{^https?://tg\.dev/})
+        return accept_invite_link(link)
+      end
+      safe_native { @native.join_chat(peer_id(chat)) }
+    end
+
+    def accept_invite_link(link)
+      result = safe_native { @native.accept_invite_link(link.to_s) }
+      result ? Types::Peer.new(result) : nil
+    end
+
+    def download_profile_photo(entity, path)
+      safe_native { @native.download_profile_photo(peer_id(entity), path.to_s) }
+    end
+
+    def iter_admin_log(chat, limit: 100, query: nil, filter: nil)
+      filter_hash = filter.is_a?(Hash) ? filter.transform_keys(&:to_sym) : filter
+      safe_native { @native.iter_admin_log(peer_id(chat), limit, query, filter_hash) }.map { |h| Types::AdminLogEvent.new(h) }
+    end
+    alias_method :get_admin_log, :iter_admin_log
+
+    def edit_title(chat, title)
+      safe_native { @native.edit_title(peer_id(chat), title.to_s) }
+    end
+
+    def edit_photo(chat, path)
+      safe_native { @native.edit_photo(peer_id(chat), path.to_s) }
+    end
+
+    def get_stats(chat)
+      safe_native { @native.get_stats(peer_id(chat)) }
+    end
+
+    def export_invite_link(chat)
+      safe_native { @native.export_invite_link(peer_id(chat)) }
+    end
+
+    def block_user(user)
+      safe_native { @native.block_user(peer_id(user)) }
+    end
+
+    def unblock_user(user)
+      safe_native { @native.unblock_user(peer_id(user)) }
+    end
+
+    def create_group(title, users)
+      user_ids = Array(users).map { |u| peer_id(u) }
+      Types::Peer.new(safe_native { @native.create_group(title.to_s, user_ids) })
+    end
+
+    def create_channel(title, about: "")
+      Types::Peer.new(safe_native { @native.create_channel(title.to_s, about.to_s, false) })
+    end
+
+    def create_supergroup(title, about: "")
+      Types::Peer.new(safe_native { @native.create_channel(title.to_s, about.to_s, true) })
+    end
+
+    def edit_about(chat, about)
+      safe_native { @native.edit_about(peer_id(chat), about.to_s) }
+    end
+
+    def get_full_chat(chat)
+      Types::ChatFull.new(safe_native { @native.get_full_chat(peer_id(chat)) })
+    end
+
+    # --- Keyboards ---
+
+    def send_reply_keyboard(chat, text, keys, parse_mode: nil, resize: true, single_use: false, placeholder: nil)
+      send_message(chat, text, parse_mode: parse_mode, reply_markup: {
+        type: :reply_keyboard, keys: build_keys(keys),
+        resize: resize, single_use: single_use, placeholder: placeholder
+      })
+    end
+
+    def remove_keyboard(chat, text = "Keyboard removed.", parse_mode: nil)
+      send_message(chat, text, parse_mode: parse_mode, reply_markup: { type: :remove_keyboard })
+    end
+
+    def force_reply(chat, text, parse_mode: nil)
+      send_message(chat, text, parse_mode: parse_mode, reply_markup: { type: :force_reply })
+    end
+
+    # --- Files ---
+
+    def send_file(chat, path, caption: nil, parse_mode: nil, reply_to: nil, silent: false, schedule: nil, buttons: nil, reply_markup: nil)
+      markup = reply_markup || (buttons ? build_buttons(buttons) : nil)
+      h = safe_native { @native.send_file(peer_id(chat), path.to_s, (caption || "").to_s, parse_mode, reply_to, silent, schedule&.to_i, markup) }
+      wrap_message(h)
+    end
+
+    def send_photo(chat, path, caption: nil, parse_mode: nil, reply_to: nil, silent: false, schedule: nil, buttons: nil, reply_markup: nil)
+      markup = reply_markup || (buttons ? build_buttons(buttons) : nil)
+      h = safe_native { @native.send_photo(peer_id(chat), path.to_s, (caption || "").to_s, parse_mode, reply_to, silent, schedule&.to_i, markup) }
+      wrap_message(h)
+    end
+
+    def send_audio(chat, path, caption: nil, parse_mode: nil, duration: 0, title: nil, performer: nil, reply_to: nil, silent: false, schedule: nil, buttons: nil, reply_markup: nil)
+      markup = reply_markup || (buttons ? build_buttons(buttons) : nil)
+      h = safe_native { @native.send_audio(peer_id(chat), path.to_s, (caption || "").to_s, parse_mode, duration, title, performer, reply_to, silent, schedule&.to_i, markup) }
+      wrap_message(h)
+    end
+
+    def send_video(chat, path, caption: nil, parse_mode: nil, duration: 0, width: 0, height: 0, supports_streaming: true, round_message: false, reply_to: nil, silent: false, schedule: nil, buttons: nil, reply_markup: nil)
+      markup = reply_markup || (buttons ? build_buttons(buttons) : nil)
+      h = safe_native { @native.send_video(peer_id(chat), path.to_s, (caption || "").to_s, parse_mode, duration, width, height, supports_streaming, round_message, reply_to, silent, schedule&.to_i, markup) }
+      wrap_message(h)
+    end
+
+    def send_voice(chat, path, caption: nil, parse_mode: nil, duration: 0, waveform: nil, reply_to: nil, silent: false, schedule: nil, buttons: nil, reply_markup: nil)
+      markup = reply_markup || (buttons ? build_buttons(buttons) : nil)
+      h = safe_native { @native.send_voice(peer_id(chat), path.to_s, (caption || "").to_s, parse_mode, duration, waveform, reply_to, silent, schedule&.to_i, markup) }
+      wrap_message(h)
+    end
+
+    def send_album(chat, *media_items, reply_to: nil, silent: false, buttons: nil, reply_markup: nil)
+      markup = reply_markup || (buttons ? build_buttons(buttons) : nil)
+      items = media_items.flatten.map do |item|
+        item.is_a?(String) ? { path: item } : item
+      end
+      safe_native { @native.send_album(peer_id(chat), items, reply_to, silent, markup) }.map { |h| h ? wrap_message(h) : nil }
+    end
+
+    def download_media(chat, message_id, path, &progress)
+      if progress
+        safe_native { @native.start_download_media(peer_id(chat), message_id, path.to_s) }
+        loop do
+          p = @native.poll_download_progress
+          if p
+            progress.call(p[:downloaded], p[:total])
+            break if p[:done]
+          else
+            sleep 0.05
+          end
+        end
+      else
+        safe_native { @native.download_media(peer_id(chat), message_id, path.to_s) }
+      end
+    end
+
+    # --- Special Media ---
+
+    def send_location(chat, lat, long, accuracy_radius: nil, reply_to: nil, silent: false, schedule: nil, buttons: nil, reply_markup: nil)
+      markup = reply_markup || (buttons ? build_buttons(buttons) : nil)
+      h = safe_native { @native.send_location(peer_id(chat), lat.to_f, long.to_f, accuracy_radius, reply_to, silent, schedule&.to_i, markup) }
+      wrap_message(h)
+    end
+
+    def send_venue(chat, lat, long, title:, address:, provider: "", venue_id: "", venue_type: "", reply_to: nil, silent: false, schedule: nil, buttons: nil, reply_markup: nil)
+      markup = reply_markup || (buttons ? build_buttons(buttons) : nil)
+      h = safe_native { @native.send_venue(peer_id(chat), lat.to_f, long.to_f, title.to_s, address.to_s, provider.to_s, venue_id.to_s, venue_type.to_s, reply_to, silent, schedule&.to_i, markup) }
+      wrap_message(h)
+    end
+
+    def send_contact(chat, phone_number:, first_name:, last_name: "", vcard: "", reply_to: nil, silent: false, schedule: nil, buttons: nil, reply_markup: nil)
+      markup = reply_markup || (buttons ? build_buttons(buttons) : nil)
+      h = safe_native { @native.send_contact(peer_id(chat), phone_number.to_s, first_name.to_s, last_name.to_s, vcard.to_s, reply_to, silent, schedule&.to_i, markup) }
+      wrap_message(h)
+    end
+
+    def send_dice(chat, emoticon: "\u{1F3B2}", reply_to: nil, silent: false, schedule: nil, buttons: nil, reply_markup: nil)
+      markup = reply_markup || (buttons ? build_buttons(buttons) : nil)
+      h = safe_native { @native.send_dice(peer_id(chat), emoticon.to_s, reply_to, silent, schedule&.to_i, markup) }
+      wrap_message(h)
+    end
+
+    def send_sticker(chat, path, reply_to: nil, silent: false, schedule: nil, buttons: nil, reply_markup: nil)
+      markup = reply_markup || (buttons ? build_buttons(buttons) : nil)
+      h = safe_native { @native.send_sticker(peer_id(chat), path.to_s, reply_to, silent, schedule&.to_i, markup) }
+      wrap_message(h)
+    end
+
+    def send_animation(chat, path, caption: nil, parse_mode: nil, duration: 0, width: 0, height: 0, reply_to: nil, silent: false, schedule: nil, buttons: nil, reply_markup: nil)
+      markup = reply_markup || (buttons ? build_buttons(buttons) : nil)
+      h = safe_native { @native.send_animation(peer_id(chat), path.to_s, (caption || "").to_s, parse_mode, duration, width, height, reply_to, silent, schedule&.to_i, markup) }
+      wrap_message(h)
+    end
+
+    # --- Bots ---
+
+    def inline_query(bot, query, limit: 20)
+      safe_native { @native.inline_query(peer_id(bot), query.to_s, limit) }.map { |h| Types::InlineResult.new(h) }
+    end
+
+    def answer_callback_query(query_id, text: nil, alert: false, cache_time: nil)
+      safe_native { @native.answer_callback_query(query_id, text, alert, cache_time) }
+    end
+
+    def answer_inline_query(query_id, results, cache_time: nil, is_personal: false, next_offset: nil)
+      safe_native { @native.answer_inline_query(query_id, Array(results), cache_time, is_personal, next_offset) }
+    end
+
+    # --- Payments ---
+
+    def send_invoice(chat, title:, description:, payload:, currency: "XTR", amount:, photo_url: nil)
+      h = safe_native { @native.send_invoice(peer_id(chat), title, description, payload, currency, amount, photo_url) }
+      wrap_message(h) if h
+    end
+
+    def create_invoice_link(title:, description:, payload:, currency: "XTR", amount:)
+      safe_native { @native.create_invoice_link(title, description, payload, currency, amount) }
+    end
+
+    def answer_pre_checkout_query(query_id, ok:, error_message: nil)
+      safe_native { @native.answer_pre_checkout_query(query_id, ok, error_message) }
+    end
+
+    def refund_star_payment(user_id, charge_id:)
+      safe_native { @native.refund_star_payment(peer_id(user_id), charge_id) }
+    end
+
+    def get_star_transactions(offset: "", limit: 100, inbound: false, outbound: false)
+      safe_native { @native.get_star_transactions(offset, limit, inbound, outbound) }
+    end
+
+    # --- Sessions ---
+
+    def export_session
+      raise Errors::Error, "Session file not found: #{@session_path}" unless File.exist?(@session_path)
+      Base64.strict_encode64(File.binread(@session_path))
+    end
+
+    def self.import_session(session_string, path: "grammerb.session")
+      File.binwrite(path, Base64.strict_decode64(session_string))
+    end
+
+    # --- Events ---
+
+    # Register an event handler. Returns the handler object (pass to off() to remove).
+    def on(event_class, pattern: nil, chats: nil, &block)
+      handler = Events::Handler.new(event_class, pattern: pattern, chats: chats && Set.new(Array(chats)), &block)
+      @handlers_mu.synchronize do
+        @handlers << handler
+        @handlers_snapshot = @handlers.dup.freeze
+      end
+      handler
+    end
+
+    def off(handler)
+      @handlers_mu.synchronize do
+        @handlers.delete(handler)
+        @handlers_snapshot = @handlers.dup.freeze
+      end
+    end
+
+    def run
+      safe_native { @native.start_update_loop }
+      @running_mu.synchronize { @running = true }
+      @logger.info("Update loop started")
+
+      # Install signal handlers for graceful shutdown
+      prev_int = trap("INT") { stop; disconnect }
+      prev_term = trap("TERM") { stop; disconnect }
+
+      album_buffer = {}   # grouped_id => [event, ...]
+      album_timers = {}   # grouped_id => Time
+
+      while @running_mu.synchronize { @running }
+        begin
+          # Flush expired album buffers (>300ms old)
+          unless album_timers.empty?
+            now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            album_timers.keys.each do |gid|
+              if now - album_timers[gid] > 0.3
+                flush_album(album_buffer.delete(gid), album_timers)
+                album_timers.delete(gid)
+              end
+            end
+          end
+
+          # Blocking wait — releases GVL, wakes on update or timeout.
+          # Short timeout when buffering albums so we flush them promptly.
+          timeout = album_timers.empty? ? 300 : 50
+          raw = safe_native { @native.poll_update_blocking(timeout) }
+          next unless raw
+
+          event = Events.from_raw(raw)
+          next unless event
+
+          event.client = self
+
+          # Buffer album messages
+          if event.respond_to?(:grouped_id) && event.grouped_id && event.is_a?(Events::NewMessage)
+            gid = event.grouped_id
+            album_buffer[gid] ||= []
+            album_buffer[gid] << event
+            album_timers[gid] ||= Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          else
+            dispatch_event(event)
+          end
+        rescue Errors::Error => e
+          @logger.error("Event loop error: #{e.class}: #{e.message}")
+        rescue RuntimeError => e
+          @logger.error("Event loop error: #{e.message}")
+        end
+      end
+
+      # Flush remaining album buffers on stop
+      album_buffer.each_value { |events| flush_album(events, album_timers) }
+      @logger.info("Update loop ended")
+    ensure
+      # Restore previous signal handlers
+      trap("INT", prev_int || "DEFAULT")
+      trap("TERM", prev_term || "DEFAULT")
+    end
+
+    def stop
+      @running_mu.synchronize { @running = false }
+      @logger.info("Update loop stopping, waiting for handlers...")
+      @handler_pool.shutdown
+      @logger.info("Stopped")
+    end
+
+    def each_update(&block)
+      safe_native { @native.start_update_loop }
+      @running_mu.synchronize { @running = true }
+
+      prev_int = trap("INT") { stop; disconnect }
+      prev_term = trap("TERM") { stop; disconnect }
+
+      while @running_mu.synchronize { @running }
+        raw = safe_native { @native.poll_update_blocking(300) }
+        if raw
+          event = Events.from_raw(raw)
+          if event
+            event.client = self
+            yield event
+          end
+        end
+      end
+    ensure
+      trap("INT", prev_int || "DEFAULT")
+      trap("TERM", prev_term || "DEFAULT")
+    end
+
+    # --- Conversations ---
+
+    # Open an exclusive conversation with a chat. Events for this chat are
+    # routed to the conversation and skip normal handlers while active.
+    #
+    #   client.conversation(chat_id, timeout: 30) do |conv|
+    #     conv.send_message("What's your name?")
+    #     response = conv.get_response
+    #     conv.send_message("Hello #{response.text}!")
+    #     conv.send_message("Pick one:", buttons: [[{text: "A", callback_data: "a"}]])
+    #     cb = conv.get_callback
+    #     cb.answer(text: "You picked #{cb.data_str}")
+    #   end
+    #
+    # Open an exclusive conversation with a chat. Spawns a dedicated thread
+    # so the handler pool is never blocked — thousands of concurrent
+    # conversations work fine (threads sleep on Queue#pop, releasing the GVL).
+    #
+    # Returns the Thread running the conversation block.
+    def conversation(chat, timeout: 60, exclusive: true, &block)
+      cid = peer_id(chat)
+      conv = Conversation.new(self, cid, timeout: timeout)
+      @conversations_mu.synchronize { @conversations[cid] = conv } if exclusive
+
+      Thread.new do
+        block.call(conv)
+      rescue Conversation::TimeoutError => e
+        @logger.debug("Conversation timeout for #{cid}: #{e.message}")
+      rescue Errors::Error => e
+        @logger.error("Conversation error for #{cid}: #{e.class}: #{e.message}")
+      rescue => e
+        @logger.error("Conversation error for #{cid}: #{e.message}")
+      ensure
+        @conversations_mu.synchronize { @conversations.delete(cid) } if exclusive
+        conv.cancel
+      end
+    end
+
+    def save_session
+      @native.save_session
+    end
+
+    # --- Raw TL ---
+
+    def invoke_raw(request_bytes)
+      safe_native { @native.invoke_raw(request_bytes) }
+    end
+
+    private
+
+    # Wrap native calls: catch RuntimeError from Rust and re-raise as Grammerb::Errors.
+    def safe_native
+      yield
+    rescue RuntimeError => e
+      raise Errors.from_native(e.message)
+    end
+
+    # Extract a usable peer identifier from any Grammerb type or raw value.
+    def peer_id(entity)
+      case entity
+      when Types::Message then entity.chat_id.to_s
+      when Types::Peer, Types::User, Types::Dialog, Types::Participant
+        entity.id.to_s
+      when Integer then entity.to_s
+      else entity.to_s
+      end
+    end
+
+    def dispatch_event(event)
+      # Route to exclusive conversation if one is active for this chat
+      if event.respond_to?(:chat_id) && event.chat_id
+        conv = @conversations_mu.synchronize { @conversations[event.chat_id.to_s] }
+        if conv
+          conv._push(event)
+          return
+        end
+      end
+
+      @logger.debug("Event: #{event.class.name.split('::').last}")
+      @handlers_snapshot.each do |handler|
+        if handler.matches?(event)
+          logger = @logger
+          @handler_pool.schedule do
+            handler.block.call(event)
+          rescue Errors::FloodWait => ex
+            logger.warn("FloodWait in handler: sleeping #{ex.seconds}s")
+            sleep(ex.seconds)
+          rescue Errors::Error => ex
+            logger.error("Grammerb error in handler: #{ex.class}: #{ex.message}")
+          rescue => ex
+            logger.error("Handler error: #{ex.message}\n#{ex.backtrace&.first(5)&.join("\n")}")
+          end
+        end
+      end
+    end
+
+    def flush_album(events, _timers)
+      return if events.nil? || events.empty?
+      album = Events::Album.new(events)
+      album.client = self
+      dispatch_event(album)
+      events.each { |e| dispatch_event(e) }
+    end
+
+    def wrap_message(hash)
+      msg = Types::Message.new(hash)
+      msg.client = self
+      msg
+    end
+
+    def default_logger
+      l = Logger.new($stderr)
+      l.level = Logger::WARN
+      l.progname = "Grammerb"
+      l
+    end
+
+    # Convert Ruby button arrays to the format expected by native methods.
+    # Accepts: [[{text: "Btn", callback_data: "d"}, {text: "Link", url: "..."}]]
+    def build_buttons(buttons)
+      buttons.map do |row|
+        row.map { |btn| btn.transform_keys(&:to_sym) }
+      end
+    end
+
+    # Convert Ruby key arrays to the format expected by native methods.
+    # Accepts: [[{text: "Option A"}, {text: "Share Phone", request_phone: true}]]
+    def build_keys(keys)
+      keys.map do |row|
+        row.map { |key| key.is_a?(String) ? { text: key } : key.transform_keys(&:to_sym) }
+      end
+    end
+  end
+end