max_bot_api 0.1.0

data/lib/max_bot_api/builders/message_builder.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module MaxBotApi
+  module Builders
+    # Builder for message payloads.
+    class MessageBuilder
+      attr_reader :user_id, :chat_id, :reset
+
+      # Create a builder from an existing hash payload.
+      # @param hash [Hash]
+      # @return [MessageBuilder]
+      def self.from_hash(hash)
+        builder = new
+        return builder if hash.nil?
+
+        builder.set_user(hash[:user_id] || hash['user_id']) if hash.key?(:user_id) || hash.key?('user_id')
+        builder.set_chat(hash[:chat_id] || hash['chat_id']) if hash.key?(:chat_id) || hash.key?('chat_id')
+        builder.set_reset(hash[:reset] || hash['reset']) if hash.key?(:reset) || hash.key?('reset')
+
+        payload = hash[:message] || hash['message'] || hash
+        builder.apply_payload(payload)
+        builder
+      end
+
+      # Initialize a new builder with empty payload.
+      def initialize
+        @user_id = nil
+        @chat_id = nil
+        @reset = false
+        @message = {
+          attachments: []
+        }
+      end
+
+      # Set recipient user ID.
+      def set_user(user_id)
+        @user_id = user_id
+        self
+      end
+
+      # Set recipient chat ID.
+      def set_chat(chat_id)
+        @chat_id = chat_id
+        self
+      end
+
+      # Toggle reset mode (skip Authorization header).
+      def set_reset(reset)
+        @reset = !!reset
+        self
+      end
+
+      # Set message text.
+      def set_text(text)
+        @message[:text] = text
+        self
+      end
+
+      # Set message format (markdown/html).
+      def set_format(format)
+        @message[:format] = format
+        self
+      end
+
+      # Toggle notification flag.
+      def set_notify(notify)
+        @message[:notify] = notify
+        self
+      end
+
+      # Set reply with explicit message ID.
+      def set_reply(text, message_id)
+        @message[:text] = text
+        @message[:link] = { type: 'reply', mid: message_id }
+        self
+      end
+
+      # Reply to a message hash with inferred recipient.
+      def reply(text, reply_message)
+        recipient = reply_message[:recipient] || reply_message['recipient'] || {}
+        set_user(recipient[:user_id] || recipient['user_id']) if recipient[:user_id] || recipient['user_id']
+        set_chat(recipient[:chat_id] || recipient['chat_id']) if recipient[:chat_id] || recipient['chat_id']
+
+        body = reply_message[:body] || reply_message['body'] || {}
+        @message[:text] = text
+        @message[:link] = { type: 'reply', mid: body[:mid] || body['mid'] }
+        self
+      end
+
+      # Add user mention markup.
+      def add_markup(user_id, from, length)
+        @message[:markup] ||= []
+        @message[:markup] << { user_id: user_id, from: from, length: length, type: 'user_mention' }
+        self
+      end
+
+      # Attach a keyboard.
+      def add_keyboard(keyboard)
+        payload = keyboard.is_a?(Builders::KeyboardBuilder) ? keyboard.build : keyboard
+        add_attachment(type: 'inline_keyboard', payload: payload)
+      end
+
+      # Attach a photo payload.
+      def add_photo(photo_tokens)
+        payload = photo_tokens.is_a?(Hash) ? photo_tokens : { photos: photo_tokens }
+        add_attachment(type: 'image', payload: { photos: payload[:photos] || payload['photos'] })
+      end
+
+      # Attach audio payload.
+      def add_audio(uploaded_info)
+        add_attachment(type: 'audio', payload: uploaded_info)
+      end
+
+      # Attach video payload.
+      def add_video(uploaded_info)
+        add_attachment(type: 'video', payload: uploaded_info)
+      end
+
+      # Attach file payload.
+      def add_file(uploaded_info)
+        add_attachment(type: 'file', payload: uploaded_info)
+      end
+
+      # Attach a location.
+      def add_location(lat, lon)
+        add_attachment(type: 'location', latitude: lat, longitude: lon)
+      end
+
+      # Attach a contact card.
+      def add_contact(name:, contact_id:, vcf_info: nil, vcf_phone: nil)
+        payload = {
+          name: name,
+          contact_id: contact_id,
+          vcf_info: vcf_info,
+          vcf_phone: vcf_phone
+        }.compact
+        add_attachment(type: 'contact', payload: payload)
+      end
+
+      # Attach a sticker.
+      def add_sticker(code)
+        add_attachment(type: 'sticker', payload: { code: code })
+      end
+
+      # Set bot token for reset mode.
+      def set_bot_token(token)
+        @message[:bot_token] = token
+        self
+      end
+
+      # Set phone numbers for notify/exists.
+      def set_phone_numbers(numbers)
+        @message[:phone_numbers] = Array(numbers)
+        self
+      end
+
+      # Return bot token used for reset mode.
+      def bot_token
+        @message[:bot_token]
+      end
+
+      # Return phone numbers used for notify/exists.
+      def phone_numbers
+        @message[:phone_numbers]
+      end
+
+      # Whether reset mode is enabled.
+      def reset?
+        @reset
+      end
+
+      # Return the message payload hash.
+      def to_h
+        @message
+      end
+
+      protected
+
+      def apply_payload(payload)
+        return if payload.nil?
+
+        payload.each do |key, value|
+          @message[key.to_sym] = value
+        end
+      end
+
+      private
+
+      def add_attachment(attachment)
+        @message[:attachments] ||= []
+        @message[:attachments] << attachment
+        self
+      end
+    end
+  end
+end

data/lib/max_bot_api/client.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module MaxBotApi
+  # Main API client. Holds auth config and provides resource accessors.
+  class Client
+    # Default API base URL.
+    DEFAULT_BASE_URL = 'https://botapi.max.ru/'
+    # Default API version appended as query param.
+    DEFAULT_VERSION = '1.2.5'
+    # Default pause between update polling loops.
+    DEFAULT_PAUSE = 1
+    # Default limit for updates requests.
+    DEFAULT_UPDATES_LIMIT = 50
+    # Max retry attempts for update polling.
+    MAX_RETRIES = 3
+
+    # @return [String] bot token
+    # @return [String] base URL
+    # @return [String] API version
+    attr_reader :token, :base_url, :version
+
+    # @param token [String] bot token
+    # @param base_url [String] API base URL
+    # @param version [String] API version
+    # @param faraday [Faraday::Connection, nil] custom Faraday connection
+    # @param adapter [Symbol] Faraday adapter
+    def initialize(token:, base_url: DEFAULT_BASE_URL, version: DEFAULT_VERSION, faraday: nil,
+                   adapter: Faraday.default_adapter)
+      raise EmptyTokenError, 'bot token is empty' if token.to_s.empty?
+
+      @token = token
+      @base_url = normalize_base_url(base_url)
+      @version = version.to_s.empty? ? DEFAULT_VERSION : version.to_s
+
+      @conn = faraday || Faraday.new(url: @base_url) do |f|
+        f.request :multipart
+        f.request :url_encoded
+        f.adapter adapter
+      end
+    end
+
+    def bots
+      Resources::Bots.new(self)
+    end
+
+    def chats
+      Resources::Chats.new(self)
+    end
+
+    def messages
+      Resources::Messages.new(self)
+    end
+
+    def subscriptions
+      Resources::Subscriptions.new(self)
+    end
+
+    def uploads
+      Resources::Uploads.new(self)
+    end
+
+    # Build a debug sender bound to a chat.
+    # @param chat_id [Integer]
+    def debugs(chat_id: 0)
+      Resources::Debugs.new(self, chat_id: chat_id)
+    end
+
+    # Fetch updates from the API.
+    # @param limit [Integer, nil]
+    # @param timeout [Integer, nil]
+    # @param marker [Integer, nil]
+    # @param types [Array<String>, nil]
+    # @param debug [Boolean]
+    def get_updates(limit: nil, timeout: nil, marker: nil, types: nil, debug: false)
+      query = {}
+      query['limit'] = limit if limit && limit.to_i > 0
+      query['timeout'] = timeout.to_i if timeout && timeout.to_i > 0
+      query['marker'] = marker if marker && marker.to_i > 0
+      Array(types).each { |t| (query['types'] ||= []) << t }
+
+      result = request(:get, 'updates', query: query)
+      Updates::Parser.parse_update_list(result, debug: debug)
+    rescue TimeoutError
+      { updates: [], marker: nil }
+    end
+
+    # Fetch updates with retry/backoff.
+    def get_updates_with_retry(limit: nil, timeout: nil, marker: nil, types: nil, debug: false)
+      last_error = nil
+
+      MAX_RETRIES.times do |attempt|
+        return get_updates(limit: limit, timeout: timeout, marker: marker, types: types, debug: debug)
+      rescue Error => e
+        last_error = e
+        raise e if attempt == MAX_RETRIES - 1
+
+        sleep(2**attempt)
+      end
+
+      raise last_error
+    end
+
+    # Returns an enumerator that yields updates indefinitely.
+    def updates_enum(pause: DEFAULT_PAUSE, limit: DEFAULT_UPDATES_LIMIT, timeout: nil, types: nil, debug: false)
+      Enumerator.new do |yielder|
+        marker = nil
+        loop do
+          updates_list = get_updates_with_retry(limit: limit, timeout: timeout, marker: marker, types: types,
+                                                debug: debug)
+          updates = Array(updates_list[:updates])
+
+          updates.each { |update| yielder << update }
+          marker = updates_list[:marker] if updates_list[:marker]
+
+          sleep(pause)
+        end
+      end
+    end
+
+    # Iterates over updates, yielding each update hash.
+    def each_update(pause: DEFAULT_PAUSE, limit: DEFAULT_UPDATES_LIMIT, timeout: nil, types: nil, debug: false, &block)
+      return updates_enum(pause: pause, limit: limit, timeout: timeout, types: types, debug: debug) unless block
+
+      updates_enum(pause: pause, limit: limit, timeout: timeout, types: types, debug: debug).each(&block)
+    end
+
+    # Parses a single webhook payload into an update hash.
+    def parse_webhook(body, debug: false)
+      Updates::Parser.parse_update(body.to_s, debug: debug)
+    end
+
+    # Perform an HTTP request.
+    # @param method [Symbol]
+    # @param path [String]
+    # @param query [Hash]
+    # @param body [Hash, Array, String, nil]
+    # @param headers [Hash]
+    # @param reset [Boolean]
+    def request(method, path, query: nil, body: nil, headers: {}, reset: false)
+      query = (query || {}).dup
+      query['v'] = version
+
+      response = @conn.public_send(method) do |req|
+        req.url(path.to_s.sub(%r{\A/}, ''))
+        req.params.update(query) unless query.empty?
+        req.headers['User-Agent'] = "max-bot-api-client-ruby/#{VERSION}"
+        req.headers['Authorization'] = token unless reset
+        headers.each { |k, v| req.headers[k] = v }
+
+        if body
+          if body.is_a?(Hash) || body.is_a?(Array)
+            if multipart_body?(body)
+              req.body = body
+            else
+              req.headers['Content-Type'] ||= 'application/json'
+              req.body = JSON.generate(body)
+            end
+          else
+            req.body = body
+          end
+        end
+      end
+
+      handle_response(response)
+    rescue Faraday::TimeoutError => e
+      raise TimeoutError.new(op: "#{method.to_s.upcase} #{path}", reason: e.message)
+    rescue Faraday::ConnectionFailed, Faraday::SSLError, Faraday::Error => e
+      raise NetworkError.new(op: "#{method.to_s.upcase} #{path}", original_error: e)
+    rescue JSON::GeneratorError => e
+      raise SerializationError.new(op: 'marshal', type: 'request body', original_error: e)
+    end
+
+    def http_client
+      @conn
+    end
+
+    private
+
+    def normalize_base_url(url)
+      uri = URI.parse(url.to_s)
+      raise InvalidUrlError, 'invalid API URL' if uri.scheme.nil? || uri.host.nil?
+
+      normalized = uri.to_s
+      normalized.end_with?('/') ? normalized : "#{normalized}/"
+    rescue URI::InvalidURIError => e
+      raise InvalidUrlError, "invalid API URL: #{e.message}"
+    end
+
+    def multipart_body?(body)
+      body.values.any? { |value| value.is_a?(Faraday::Multipart::FilePart) }
+    end
+
+    def handle_response(response)
+      return parse_body(response) if response.status == 200
+
+      api_message = parse_error_message(response)
+      raise ApiError.new(code: response.status, message: api_message)
+    end
+
+    def parse_body(response)
+      content_type = response.headers['content-type'].to_s
+      return response.body unless content_type.include?('application/json')
+
+      body = response.body.to_s
+      return nil if body.empty?
+
+      JSON.parse(body, symbolize_names: true)
+    end
+
+    def parse_error_message(response)
+      body = response.body.to_s
+      return response.reason_phrase.to_s if body.empty?
+
+      json = JSON.parse(body)
+      return json['error'] if json.is_a?(Hash) && json['error']
+      return json['message'] if json.is_a?(Hash) && json['message']
+
+      response.reason_phrase.to_s
+    rescue JSON::ParserError
+      response.reason_phrase.to_s
+    end
+  end
+end

data/lib/max_bot_api/errors.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module MaxBotApi
+  # Base error for all library exceptions.
+  class Error < StandardError; end
+
+  # Raised when the bot token is missing.
+  class EmptyTokenError < Error; end
+  # Raised when the base URL is invalid.
+  class InvalidUrlError < Error; end
+
+  # Raised when the API responds with a non-200 status code.
+  class ApiError < Error
+    attr_reader :code, :message, :details
+
+    # @param code [Integer] HTTP status code
+    # @param message [String] error message
+    # @param details [String, nil] optional details
+    def initialize(code:, message:, details: nil)
+      @code = code
+      @message = message
+      @details = details
+      super(build_message)
+    end
+
+    def ==(other)
+      other.is_a?(ApiError) && other.code == code
+    end
+
+    private
+
+    def build_message
+      return "API error #{code}: #{message} (#{details})" if details && !details.empty?
+
+      "API error #{code}: #{message}"
+    end
+  end
+
+  # Raised when the HTTP request fails before reaching the API.
+  class NetworkError < Error
+    attr_reader :op, :original_error
+
+    # @param op [String] operation name
+    # @param original_error [Exception] original error
+    def initialize(op:, original_error:)
+      @op = op
+      @original_error = original_error
+      super("network error during #{op}: #{original_error}")
+    end
+  end
+
+  # Raised when the request times out.
+  class TimeoutError < Error
+    attr_reader :op, :reason
+
+    # @param op [String] operation name
+    # @param reason [String, nil] timeout reason
+    def initialize(op:, reason: nil)
+      @op = op
+      @reason = reason
+      super(build_message)
+    end
+
+    def timeout?
+      true
+    end
+
+    private
+
+    def build_message
+      return "timeout error during #{op}: #{reason}" if reason && !reason.empty?
+
+      "timeout error during #{op}"
+    end
+  end
+
+  # Raised when serialization or parsing fails.
+  class SerializationError < Error
+    attr_reader :op, :type, :original_error
+
+    # @param op [String] operation name
+    # @param type [String] serialized object type
+    # @param original_error [Exception] original error
+    def initialize(op:, type:, original_error:)
+      @op = op
+      @type = type
+      @original_error = original_error
+      super("serialization error during #{op} of #{type}: #{original_error}")
+    end
+  end
+end

data/lib/max_bot_api/resources/bots.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module MaxBotApi
+  module Resources
+    # Bots API methods.
+    class Bots
+      def initialize(client)
+        @client = client
+      end
+
+      # Get current bot info.
+      def get_bot
+        @client.request(:get, 'me')
+      end
+
+      # Patch current bot info.
+      # @param patch [Hash]
+      def patch_bot(patch)
+        @client.request(:patch, 'me', body: patch)
+      end
+    end
+  end
+end

data/lib/max_bot_api/resources/chats.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module MaxBotApi
+  module Resources
+    # Chats API methods.
+    class Chats
+      def initialize(client)
+        @client = client
+      end
+
+      # List chats with pagination.
+      # @param count [Integer, nil]
+      # @param marker [Integer, nil]
+      def get_chats(count: nil, marker: nil)
+        query = {}
+        query['count'] = count if count && count.to_i > 0
+        query['marker'] = marker if marker && marker.to_i > 0
+        @client.request(:get, 'chats', query: query)
+      end
+
+      # Fetch a single chat.
+      # @param chat_id [Integer]
+      def get_chat(chat_id:)
+        @client.request(:get, "chats/#{chat_id}")
+      end
+
+      # Fetch current bot membership info.
+      # @param chat_id [Integer]
+      def get_chat_membership(chat_id:)
+        @client.request(:get, "chats/#{chat_id}/members/me")
+      end
+
+      # List chat members.
+      # @param chat_id [Integer]
+      def get_chat_members(chat_id:, count: nil, marker: nil)
+        query = {}
+        query['count'] = count if count && count.to_i > 0
+        query['marker'] = marker unless marker.nil?
+        @client.request(:get, "chats/#{chat_id}/members", query: query)
+      end
+
+      # Fetch specific members by user IDs.
+      # @param chat_id [Integer]
+      # @param user_ids [Array<Integer>]
+      def get_specific_chat_members(chat_id:, user_ids:)
+        ids = Array(user_ids).map(&:to_s).join(',')
+        @client.request(:get, "chats/#{chat_id}/members", query: { 'user_ids' => ids })
+      end
+
+      # List chat admins.
+      # @param chat_id [Integer]
+      def get_chat_admins(chat_id:)
+        @client.request(:get, "chats/#{chat_id}/members/admins")
+      end
+
+      # Leave a chat.
+      # @param chat_id [Integer]
+      def leave_chat(chat_id:)
+        @client.request(:delete, "chats/#{chat_id}/members/me")
+      end
+
+      # Patch chat info.
+      # @param chat_id [Integer]
+      # @param update [Hash]
+      def edit_chat(chat_id:, update:)
+        @client.request(:patch, "chats/#{chat_id}", body: update)
+      end
+
+      # Add members to chat.
+      # @param chat_id [Integer]
+      # @param users [Hash]
+      def add_member(chat_id:, users:)
+        @client.request(:post, "chats/#{chat_id}/members", body: users)
+      end
+
+      # Remove a member from chat.
+      # @param chat_id [Integer]
+      # @param user_id [Integer]
+      def remove_member(chat_id:, user_id:)
+        @client.request(:delete, "chats/#{chat_id}/members", query: { 'user_id' => user_id })
+      end
+
+      # Send a chat action.
+      # @param chat_id [Integer]
+      # @param action [String]
+      def send_action(chat_id:, action:)
+        @client.request(:post, "chats/#{chat_id}/actions", body: { action: action })
+      end
+    end
+  end
+end

data/lib/max_bot_api/resources/debugs.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module MaxBotApi
+  module Resources
+    # Debug helper for sending raw updates/errors to a chat.
+    class Debugs
+      def initialize(client, chat_id: 0)
+        @client = client
+        @chat_id = chat_id
+      end
+
+      # Send raw update debug text to the configured chat.
+      # @param update [Hash]
+      def send(update)
+        message = Builders::MessageBuilder.new
+                                          .set_chat(@chat_id)
+                                          .set_text(update[:debug_raw].to_s)
+
+        @client.request(:post, 'messages', query: { 'chat_id' => @chat_id }, body: message.to_h)
+        true
+      end
+
+      # Send an error message to the configured chat.
+      # @param error [Exception, String]
+      def send_err(error)
+        message = Builders::MessageBuilder.new
+                                          .set_chat(@chat_id)
+                                          .set_text(error.to_s)
+
+        @client.request(:post, 'messages', query: { 'chat_id' => @chat_id }, body: message.to_h)
+        true
+      end
+    end
+  end
+end