kybus-bot 0.11.3 → 0.11.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5621cdb73308df7a7580e484959a825170aa1e9028c3ad55950c86a4ca6f5a2c
-  data.tar.gz: caec550063dfc742d65687f8c8dda7de87cb91acb4409c9b81ac823e52843f14
+  metadata.gz: 688379f443d3679dba44474a96c6068755df45f81c8972cb3e715a0561722fd5
+  data.tar.gz: b5a21e91866dc4cd1dfd79f73b4556acf11a436d0ec4ae8127a67661b673bbc9
 SHA512:
-  metadata.gz: 98558bf269ec8e876e76eeca9c0ecbc308424db2dd14697f1ef8813e42e917fb1603875a6c3cf541ba5707ec0c2c3e6d86fbd972c13c95e8a0b8f39d5e664a65
-  data.tar.gz: bf47207fae0a45f1608470f480175a9ae4084a96080197bece81c2f793d87c4a4fc5b41bd743c838a6359e64fc743ef94d2014b81b9d4c766e0c29ecc7d73451
+  metadata.gz: 3b19d61d37bd6a50b214747c258880719e094ab538d77d86a6a1f7a85327c8d046826e7c2213857e270b93419f76806f00897fe428c5baf16b8d996fe28a66b7
+  data.tar.gz: '058300edd89b02221df1e293a320d5be930f2859420e16d7a36eef21a5fceda06f919a360594190c12660ea79aa837db214622a2b1a038e569c502c521c1eddf'

data/lib/kybus/bot/adapters/base.rb

@@ -2,11 +2,11 @@
 
 module Kybus
   module Bot
-    # Implements a factory singleton for building bot adapters
+    # Factory for building bot adapters from config.
     module Adapter
       extend Kybus::DRY::ResourceInjector
 
-      # builds the abstract adapter
+      # Builds the adapter instance for the given config.
       def self.from_config(configs)
         require_relative configs['name']
         resource(configs['name']).new(configs)

data/lib/kybus/bot/adapters/debug.rb

@@ -8,7 +8,7 @@ module Kybus
     # :nodoc: #
     module Adapter
       # :nodoc: #
-      # Wraps a debugging message inside a class.
+      # Debug message for test and development adapters.
       class DebugMessage < Kybus::Bot::Message
         # It receives a string with the raw text and the id of the channel
         attr_accessor :replied_message
@@ -80,7 +80,7 @@ module Kybus
         end
       end
 
-      # This class simulates a message chat with a user.
+      # Simulates a message channel for the debug adapter.
       class Channel
         # It is build from
         # an array of raw messages, the name of the channel and the config
@@ -128,8 +128,9 @@ module Kybus
       end
 
       ##
-      # This adapter is intended to be used on unit tests and development.
+      # Debug adapter for tests and local development.
       class Debug
+        include Kybus::Logger
         # Exception for stoping the loop of messages
         class NoMoreMessageException < Kybus::Exceptions::KybusError
           def initialize
@@ -171,26 +172,36 @@ module Kybus
         # interface for sending messages
         def send_message(contents, channel_name, attachment = nil)
           channel(channel_name).answer(contents, attachment)
+        rescue StandardError => e
+          log_error('Debug send_message failed', error: e.class, msg: e.message)
         end
 
         # interface for sending video
         def send_video(channel_name, video_url, _caption = nil)
           channel(channel_name).answer("VIDEO: #{video_url}")
+        rescue StandardError => e
+          log_error('Debug send_video failed', error: e.class, msg: e.message)
         end
 
         # interface for sending uadio
-        def send_audio(channel_name, audio_url)
+        def send_audio(channel_name, audio_url, _caption = nil)
           channel(channel_name).answer("AUDIO: #{audio_url}")
+        rescue StandardError => e
+          log_error('Debug send_audio failed', error: e.class, msg: e.message)
         end
 
         # interface for sending image
         def send_image(channel_name, image_url, _caption = nil)
           channel(channel_name).answer("IMG: #{image_url}")
+        rescue StandardError => e
+          log_error('Debug send_image failed', error: e.class, msg: e.message)
         end
 
         # interface for sending image
-        def send_document(channel_name, doc_url)
+        def send_document(channel_name, doc_url, _caption = nil)
           channel(channel_name).answer("DOC: #{doc_url}")
+        rescue StandardError => e
+          log_error('Debug send_document failed', error: e.class, msg: e.message)
         end
 
         def file_builder(data)

data/lib/kybus/bot/adapters/discord.rb

@@ -7,7 +7,7 @@ module Kybus
     # :nodoc: #
     module Adapter
       # :nodoc: #
-      # Wraps a debugging message inside a class.
+      # Wraps a Discord message and exposes Kybus::Bot::Message API.
       class DiscordMessage < Kybus::Bot::Message
         # It receives a string with the raw text and the id of the channel
         def initialize(msg)
@@ -21,7 +21,7 @@ module Kybus
         end
 
         def message_id
-          nil
+          @message.id if @message.respond_to?(:id)
         end
 
         def has_attachment?
@@ -46,16 +46,20 @@ module Kybus
         end
 
         def reply?
-          @message.message.reply?
+          return false unless @message.respond_to?(:referenced_message)
+
+          !@message.referenced_message.nil?
         end
 
         def replied_message
-          DiscordMessage.new(@message.message.referenced_message)
+          return unless reply?
+
+          DiscordMessage.new(@message.referenced_message)
         end
       end
 
       ##
-      # This adapter is intended to be used on unit tests and development.
+      # Discord adapter for polling and sending messages.
       class Discord
         include ::Kybus::Logger
 
@@ -69,7 +73,7 @@ module Kybus
         def initialize(configs)
           @config = configs
           @client = Discordrb::Bot.new(token: @config['token'])
-          @pool = []
+          @pool = Queue.new
           @client.message do |msg|
             @pool << msg
           end
@@ -82,13 +86,14 @@ module Kybus
 
         # Interface for receiving message
         def read_message
-          # take the first message from the first open message,
           loop do
-            break unless @pool.empty?
-
-            sleep(0.1)
+            begin
+              msg = @pool.pop(true)
+              return @last_message = DiscordMessage.new(msg)
+            rescue ThreadError
+              sleep(0.1)
+            end
           end
-          @last_message = DiscordMessage.new(@pool.shift)
         end
 
         # interface for sending messages
@@ -100,6 +105,8 @@ module Kybus
           else
             @client.user(channel_name).pm(contents)
           end
+        rescue StandardError => e
+          log_error('Discord send_message failed', error: e.class, msg: e.message)
         end
 
         def message_builder(raw_message)
@@ -108,20 +115,34 @@ module Kybus
 
         def send_file(channel_name, file, _caption = nil)
           @client.send_file(channel_name, File.open(file, 'r'))
+        rescue StandardError => e
+          log_error('Discord send_file failed', error: e.class, msg: e.message)
         end
 
         def send_video(channel_name, file, _caption = nil)
           @client.send_file(channel_name, File.open(file, 'r'))
+        rescue StandardError => e
+          log_error('Discord send_video failed', error: e.class, msg: e.message)
         end
 
         # interface for sending uadio
         def send_audio(channel_name, file, _caption = nil)
           @client.send_file(channel_name, File.open(file, 'r'))
+        rescue StandardError => e
+          log_error('Discord send_audio failed', error: e.class, msg: e.message)
         end
 
         # interface for sending image
         def send_image(channel_name, file, _caption = nil)
           @client.send_file(channel_name, File.open(file, 'r'))
+        rescue StandardError => e
+          log_error('Discord send_image failed', error: e.class, msg: e.message)
+        end
+
+        def send_document(channel_name, file, _caption = nil)
+          @client.send_file(channel_name, File.open(file, 'r'))
+        rescue StandardError => e
+          log_error('Discord send_document failed', error: e.class, msg: e.message)
         end
       end
 

data/lib/kybus/bot/adapters/telegram.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'telegram/bot'
+require 'timeout'
 require 'faraday'
 require_relative 'telegram_file'
 require_relative 'telegram_message'
@@ -8,6 +9,7 @@ require_relative 'telegram_message'
 module Kybus
   module Bot
     module Adapter
+      # Telegram adapter for polling and sending messages.
       class Telegram
         include ::Kybus::Logger
 
@@ -19,18 +21,46 @@ module Kybus
           TelegramFile.register(:cli, @client)
         end
 
+        # Blocking read from Telegram long-polling.
         def read_message
           loop do
-            @client.listen do |message|
-              log_info('Received message', message: message.to_h, from: message.from.to_h)
-              return @last_message = TelegramMessage.new(message)
+            Timeout.timeout(30) do
+              @client.listen do |message|
+                if message.respond_to?(:data) && message.respond_to?(:message)
+                  return @last_message = serialize_callback_query(message)
+                end
+                message_hash = message.respond_to?(:to_h) ? message.to_h : {}
+                has_message_id = message.respond_to?(:message_id)
+                payload = message_hash.is_a?(Hash) ? (message_hash['result'] || message_hash[:result]) : nil
+                has_result_message_id = payload.is_a?(Hash) && payload['message_id']
+
+                unless has_message_id || has_result_message_id
+                  log_info('Skipping non-message update', type: message.class.name)
+                  next
+                end
+
+                from_hash = message.respond_to?(:from) && message.from ? message.from.to_h : nil
+                log_info('Received message', message: message_hash, from: from_hash)
+                return @last_message = TelegramMessage.new(message)
+              end
             end
           rescue ::Telegram::Bot::Exceptions::ResponseError => e
             log_error('An error occurred while calling to Telegram API', e)
+            sleep(5)
+          rescue Timeout::Error
+            log_error('Telegram read timeout, retrying')
+            sleep(2)
+          rescue StandardError => e
+            log_error('Error while reading Telegram message', error: e.class, msg: e.message)
+            sleep(5)
           end
         end
 
+        # Parse a webhook-style payload into a SerializedMessage.
         def handle_message(body)
+          if body['callback_query']
+            return serialize_callback_payload(body['callback_query'])
+          end
           chat_id = body.dig('message', 'chat', 'id')
           message_id = body.dig('message', 'message_id')
           user = extract_user(body.dig('message', 'from'))
@@ -48,6 +78,7 @@ module Kybus
           "[user](tg://user?id=#{id})"
         end
 
+        # Send a text message.
         def send_message(contents, channel_name)
           log_debug('Sending message', channel_name:, message: contents)
           @client.api.send_message(chat_id: channel_name.to_i, text: contents, parse_mode: @config['parse_mode'])
@@ -55,24 +86,49 @@ module Kybus
           nil if e.error_code == '403'
         end
 
+        # Send a text message with reply markup.
+        def send_message_with_markup(contents, channel_name, reply_markup: nil)
+          log_debug('Sending message', channel_name:, message: contents)
+          @client.api.send_message(chat_id: channel_name.to_i, text: contents, parse_mode: @config['parse_mode'],
+                                   reply_markup: reply_markup)
+        rescue ::Telegram::Bot::Exceptions::ResponseError => e
+          nil if e.error_code == '403'
+        end
+
+        # Edit an existing message.
+        def edit_message_text(channel_name, message_id, contents, reply_markup: nil)
+          @client.api.edit_message_text(chat_id: channel_name.to_i, message_id: message_id, text: contents,
+                                        parse_mode: @config['parse_mode'], reply_markup: reply_markup)
+        rescue ::Telegram::Bot::Exceptions::ResponseError => e
+          nil if e.error_code == '403'
+        end
+
         def send_video(channel_name, video_url, comment = nil)
           file = Faraday::FilePart.new(video_url, 'video/mp4')
-          @client.api.send_video(chat_id: channel_name, video: file, caption: comment)
+          @client.api.send_video(chat_id: channel_name, video: file, caption: comment, parse_mode: @config['parse_mode'])
+        rescue ::Telegram::Bot::Exceptions::ResponseError => e
+          nil if e.error_code == '403'
         end
 
-        def send_audio(channel_name, audio_url)
+        def send_audio(channel_name, audio_url, comment = nil)
           file = Faraday::FilePart.new(audio_url, 'audio/mp3')
-          @client.api.send_audio(chat_id: channel_name, audio: file)
+          @client.api.send_audio(chat_id: channel_name, audio: file, caption: comment, parse_mode: @config['parse_mode'])
+        rescue ::Telegram::Bot::Exceptions::ResponseError => e
+          nil if e.error_code == '403'
         end
 
         def send_image(channel_name, image_url, comment = nil)
           file = Faraday::FilePart.new(image_url, 'image/jpeg')
-          @client.api.send_photo(chat_id: channel_name, photo: file, caption: comment)
+          @client.api.send_photo(chat_id: channel_name, photo: file, caption: comment, parse_mode: @config['parse_mode'])
+        rescue ::Telegram::Bot::Exceptions::ResponseError => e
+          nil if e.error_code == '403'
         end
 
-        def send_document(channel_name, image_url)
+        def send_document(channel_name, image_url, comment = nil)
           file = Faraday::FilePart.new(image_url, 'application/octet-stream')
-          @client.api.send_document(chat_id: channel_name, document: file)
+          @client.api.send_document(chat_id: channel_name, document: file, caption: comment, parse_mode: @config['parse_mode'])
+        rescue ::Telegram::Bot::Exceptions::ResponseError => e
+          nil if e.error_code == '403'
         end
 
         def message_builder(raw_message)
@@ -86,7 +142,18 @@ module Kybus
         private
 
         def extract_user(from)
-          from['username'] || from['first_name']
+          return if from.nil?
+
+          if from.respond_to?(:username) || from.respond_to?(:first_name)
+            username = from.respond_to?(:username) ? from.username : nil
+            return username if username && !username.to_s.empty?
+
+            return from.first_name if from.respond_to?(:first_name)
+          end
+
+          return from[:username] || from[:first_name] if from.respond_to?(:[])
+
+          nil
         end
 
         def extract_attachment(message)
@@ -111,6 +178,37 @@ module Kybus
             is_private?: replied_message.dig('chat', 'type') == 'private'
           ).serialize
         end
+
+        def serialize_callback_query(callback)
+          msg = callback.message
+          SerializedMessage.new(
+            provider: 'telegram',
+            channel_id: msg.chat.id,
+            message_id: msg.message_id,
+            user: extract_user(callback.from),
+            replied_message: nil,
+            raw_message: callback.data,
+            is_private?: msg.chat.type == 'private',
+            callback: true,
+            attachment: nil
+          )
+        end
+
+        def serialize_callback_payload(callback)
+          msg = callback['message'] || {}
+          chat = msg['chat'] || {}
+          SerializedMessage.new(
+            provider: 'telegram',
+            channel_id: chat['id'],
+            message_id: msg['message_id'],
+            user: extract_user(callback['from'] || {}),
+            replied_message: nil,
+            raw_message: callback['data'],
+            is_private?: chat['type'] == 'private',
+            callback: true,
+            attachment: nil
+          )
+        end
       end
 
       register('telegram', Telegram)

data/lib/kybus/bot/adapters/telegram_file.rb

@@ -7,6 +7,7 @@ module Kybus
   module Bot
     # :nodoc: #
     module Adapter
+      # Telegram file wrapper with download helpers.
       class TelegramFile
         extend Kybus::DRY::ResourceInjector
         attr_reader :id

data/lib/kybus/bot/adapters/telegram_message.rb

@@ -8,7 +8,7 @@ module Kybus
     # :nodoc: #
     module Adapter
       # :nodoc: #
-      # Wraps a debugging message inside a class.
+      # Wraps a Telegram message and exposes Kybus::Bot::Message API.
       class TelegramMessage < Kybus::Bot::Message
         # It receives a string with the raw text and the id of the channel
         def initialize(message)
@@ -30,7 +30,15 @@ module Kybus
         end
 
         def message_id
-          @message.respond_to?(:message_id) ? @message.message_id : @message['result']['message_id']
+          return @message.message_id if @message.respond_to?(:message_id)
+
+          if @message.respond_to?(:to_h)
+            result = @message.to_h
+            payload = result.is_a?(Hash) ? (result['result'] || result[:result]) : nil
+            return payload['message_id'] if payload.is_a?(Hash)
+          end
+
+          nil
         end
 
         # Returns the message contents

data/lib/kybus/bot/base.rb

@@ -18,6 +18,7 @@ require 'forwardable'
 
 module Kybus
   module Bot
+    # Main bot runtime: command registry, provider IO, and state management.
     class Base # rubocop: disable Metrics/ClassLength
       extend Forwardable
       include Kybus::Logger
@@ -51,24 +52,33 @@ module Kybus
         build_pool
       end
 
+      # Extend DSL methods available inside command blocks.
       def self.helpers(mod = nil, &)
         DSLMethods.include(mod) if mod
         DSLMethods.class_eval(&) if block_given?
       end
 
+      # Enable automatic help and hints injection for commands.
+      def self.enable_command_help!
+        Kybus::Bot::CommandHelp.apply!(self)
+      end
+
       def extend(*)
         DSLMethods.include(*)
       end
 
+      # Returns the DSL context used to execute commands.
       def dsl
         @executor.dsl
       end
 
+      # Process an incoming provider message (webhook mode).
       def handle_message(msg)
         parsed = @provider.handle_message(msg)
         @executor.process_message(parsed)
       end
 
+      # Execute a background job (used by async forkers).
       def handle_job(job, args, channel_id)
         @executor.load_state!(channel_id)
         @forker.handle_job(job, args)
@@ -80,27 +90,67 @@ module Kybus
         pool.each(&:await)
       end
 
+      # Redirect execution to another command with params.
       def redirect(command, *params)
         @executor.redirect(command, params)
       end
 
+      # Send a message through the provider.
       def send_message(contents, channel)
         log_debug('Sending message', contents:, channel:)
         provider.message_builder(@provider.send_message(contents, channel))
       end
 
+      # Send a message with buttons using the active UX renderer.
+      def send_message_with_buttons(contents, buttons, channel)
+        ux.render_buttons(dsl, text: contents, buttons: buttons, channel: channel)
+      end
+
+      # Register a paginated query command with enhanced UX rendering.
+      def define_paginated_query(command, params: [], hint: nil, per_page: 10, &block)
+        register_command(command, params, hint: hint) do
+          @bot.run_paginated_query(self, command, params, per_page, &block)
+        end
+      end
+
+      # Render a paginated response using the active UX renderer.
+      def run_paginated_query(dsl, command, params, per_page, &block)
+        args = Array(params).map { |param| dsl.params[param] }
+        last_arg = args.last
+        value, page = split_value_page(last_arg || dsl.last_message.raw_message)
+        args[-1] = value if args.any?
+
+        result = block.call(dsl, *args, page, per_page)
+        total_pages = result[:total_pages] || 1
+        text = result[:text] || [result[:header], result[:body], result[:nav]].compact.join("\n")
+        key = result[:key] || "#{command}:#{args.compact.join(':')}"
+        prev_cmd = result[:prev_cmd] || (page > 1 ? build_paginated_command(command, args, page - 1) : nil)
+        next_cmd = result[:next_cmd] || (page < total_pages ? build_paginated_command(command, args, page + 1) : nil)
+
+        ux.render_paginated(dsl, key:, text:, prev_cmd:, next_cmd:)
+      end
+
+      # Returns the UX renderer for the current provider.
+      def ux
+        @ux ||= Kybus::Bot::UX.for(provider)
+      end
+
+      # Register a command and its params.
       def register_command(klass, params = [], &)
         definitions.register_command(klass, params, &)
       end
 
+      # Register a background job handler.
       def register_job(name, args = {}, &)
         @forker.register_command(name, args, &)
       end
 
+      # Enqueue a background job.
       def invoke_job(name, args)
         @forker.fork(name, args, dsl)
       end
 
+      # Enqueue a background job with delay.
       def invoke_job_with_delay(name, delay, args)
         @forker.fork(name, args, dsl, delay:)
       end
@@ -123,6 +173,20 @@ module Kybus
         Kybus::Storage::Repository.from_config(nil, repository_config, {})
       end
 
+      def split_value_page(raw)
+        token = raw.to_s
+        value, page_str = token.split(/__|\s+/, 2)
+        page = page_str.to_i
+        page = 1 if page <= 0
+        [value, page]
+      end
+
+      def build_paginated_command(command, args, page)
+        base = command.to_s
+        base += args.first.to_s if args.any? && !args.first.to_s.empty?
+        "#{base}__#{page}"
+      end
+
       def create_executor(configs, command_factory)
         @executor = if configs['sidekiq']
                       require_relative 'sidekiq_command_executor'

data/lib/kybus/bot/command/command.rb

@@ -5,6 +5,7 @@ module Kybus
     # Object that wraps a command, it is analogus to a route definition.
     # it currently only gets a param list, but it will be extended to a more
     # complex DSL.
+    # Command definition with params and executable block.
     class Command
       attr_accessor :name
       attr_reader :block, :params
@@ -23,12 +24,12 @@ module Kybus
         end
       end
 
-      # Checks if the params object given contains all the needed values
+      # Checks if the params object given contains all the needed values.
       def ready?(current_params)
         params.all? { |key| current_params.key?(key) }
       end
 
-      # Finds the first empty param from the given parameter
+      # Finds the first missing param from the given parameter set.
       def next_missing_param(current_params)
         params.find { |key| !current_params.key?(key) }.to_s
       end

data/lib/kybus/bot/command/command_definition.rb

@@ -4,12 +4,13 @@ require_relative 'command'
 
 module Kybus
   module Bot
+    # Registry for commands keyed by name/pattern.
     class CommandDefinition
       def initialize
         @commands = {}
       end
 
-      # Stores an operation definition
+      # Stores an operation definition.
       def register_command(name, params, &)
         @commands[name] = Command.new(name, params, &)
       end

data/lib/kybus/bot/command/command_handler.rb

@@ -2,6 +2,7 @@
 
 module Kybus
   module Bot
+    # Runs commands when ready or requests missing params.
     class CommandHandler
       def initialize(executor)
         @executor = executor

data/lib/kybus/bot/command/command_state.rb

@@ -2,6 +2,7 @@
 
 module Kybus
   module Bot
+    # Persisted state for a channel (command, params, files, metadata).
     class CommandState
       attr_reader :command
 
@@ -35,6 +36,7 @@ module Kybus
         command.next_missing_param(params)
       end
 
+      # Store the last message for reply context.
       def last_message=(msg)
         @data[:last_message] = msg
       end
@@ -83,12 +85,14 @@ module Kybus
         @data[:params][param] = value
       end
 
+      # Metadata hash persisted with the state.
       def metadata
         @data[:metadata] = parse_json(@data[:metadata]) if @data[:metadata].is_a?(String)
-        @data[:metadata] || {}
+        @data[:metadata] ||= {}
       end
 
       include Kybus::Logger
+      # Persist the current state into the repository.
       def save!
         backup = @data.clone
         serialize_data!

data/lib/kybus/bot/command/command_state_factory.rb

@@ -5,6 +5,7 @@ require_relative 'inline_command_matcher'
 
 module Kybus
   module Bot
+    # Factory for loading/saving command state from storage.
     class CommandStateFactory
       include Kybus::Storage::Datasource
       attr_reader :factory

data/lib/kybus/bot/command/execution_context.rb

@@ -2,6 +2,7 @@
 
 module Kybus
   module Bot
+    # Execution wrapper for a command and its state.
     class ExecutionContest
       include Kybus::Logger
       extend Forwardable
@@ -15,6 +16,7 @@ module Kybus
         state.command.block
       end
 
+      # Execute the command block with a DSL context.
       def call!(context)
         context.state = state
         statement = context.instance_eval(&block)
@@ -28,6 +30,7 @@ module Kybus
       end
 
       # Stores a parameter into the status
+      # Adds a parameter value to the current state.
       def add_param(value)
         param = state.requested_param
         return unless param
@@ -40,6 +43,7 @@ module Kybus
         state.command.nil?
       end
 
+      # Adds an uploaded file to the current state.
       def add_file(file)
         param = state.requested_param
         return unless param