max_bot 0.1.1 → 0.2.0

data/lib/max/bot/attachments.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Max
+  module Bot
+    # Builders for +attachments+ in +POST /messages+ (NewMessageBody).
+    # Types follow the MAX Bot API: image, video, audio, file, sticker, contact,
+    # inline_keyboard, location, share.
+    #
+    # @see https://dev.max.ru/docs-api/methods/POST/messages
+    # @see https://dev.max.ru/docs-api/objects/NewMessageBody
+    module Attachments
+      module_function
+
+      def prune(hash)
+        hash.reject { |_, v| v.nil? }
+      end
+
+      # --- Media (usually +token+ from +POST /uploads+ flow) ---
+
+      def image(token: nil, url: nil, photos: nil)
+        { type: 'image', payload: prune(token: token, url: url, photos: photos) }
+      end
+
+      def video(token: nil)
+        { type: 'video', payload: prune(token: token) }
+      end
+
+      def audio(token: nil)
+        { type: 'audio', payload: prune(token: token) }
+      end
+
+      def file(token: nil)
+        { type: 'file', payload: prune(token: token) }
+      end
+
+      def sticker(code:)
+        { type: 'sticker', payload: prune(code: code) }
+      end
+
+      def contact(name:, contact_id: nil, vcf_info: nil, vcf_phone: nil)
+        {
+          type: 'contact',
+          payload: prune(
+            name: name,
+            contact_id: contact_id,
+            vcf_info: vcf_info,
+            vcf_phone: vcf_phone
+          )
+        }
+      end
+
+      # +rows+ is an Array of rows; each row is an Array of button Hashes (see +callback_button+, +link_button+, …).
+      def inline_keyboard(rows)
+        { type: 'inline_keyboard', payload: { buttons: rows } }
+      end
+      alias keyboard inline_keyboard
+
+      # Per client typings, latitude/longitude sit on the attachment object (not under +payload+).
+      def location(latitude:, longitude:)
+        { type: 'location', latitude: latitude, longitude: longitude }
+      end
+
+      def share(url: nil, **payload_rest)
+        { type: 'share', payload: prune({ url: url }.merge(payload_rest)) }
+      end
+
+      # --- Inline keyboard buttons (https://dev.max.ru/docs-api keyboard section) ---
+
+      def callback_button(text, payload, intent: nil)
+        prune(type: 'callback', text: text, payload: payload, intent: intent)
+      end
+
+      def link_button(text, url)
+        { type: 'link', text: text, url: url }
+      end
+
+      def request_contact_button(text)
+        { type: 'request_contact', text: text }
+      end
+
+      def request_geo_location_button(text, quick: nil)
+        prune(type: 'request_geo_location', text: text, quick: quick)
+      end
+
+      # Some integrations use +chat+ for deep-link style buttons; pass API fields you need.
+      def chat_button(text, chat_title:, chat_description: nil, start_payload: nil, uuid: nil)
+        prune(
+          type: 'chat',
+          text: text,
+          chat_title: chat_title,
+          chat_description: chat_description,
+          start_payload: start_payload,
+          uuid: uuid
+        )
+      end
+
+      def message_button(text, payload: nil)
+        prune(type: 'message', text: text, payload: payload)
+      end
+
+      # Escape hatch for new API button/attachment shapes.
+      def raw(type:, payload: nil, **top_level)
+        h = { type: type }
+        h[:payload] = payload unless payload.nil?
+        prune(h.merge(top_level))
+      end
+    end
+  end
+end

data/lib/max/bot/client.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Max
+  module Bot
+    # Polls the MAX Bot API with GET /updates and yields each update to your block.
+    class Client
+      attr_reader :api, :options
+
+      def self.run(token, **options, &block)
+        raise ArgumentError, 'block required' unless block
+
+        new(token, **options).run(&block)
+      end
+
+      def initialize(token, **options)
+        @options = default_options.merge(options)
+        url = @options.delete(:url) || Api::DEFAULT_URL
+        @api = @options.delete(:api) || Api.new(token, url: url)
+      end
+
+      def run(&block)
+        raise ArgumentError, 'block required' unless block
+
+        marker = options[:marker]
+        limit = options.fetch(:limit, 100)
+        timeout = options.fetch(:timeout, 30)
+        types = options[:types]
+        backoff = options.fetch(:error_backoff, 3).to_f
+        backoff = 0.5 if backoff < 0.5
+
+        loop do
+          result = fetch_updates(marker: marker, limit: limit, timeout: timeout, types: types)
+          marker = advance_marker(result, marker)
+          deliver_updates(result, &block)
+        rescue Interrupt
+          raise
+        rescue ApiError, Faraday::Error => e
+          handle_poll_error(e, backoff)
+        end
+      end
+
+      private
+
+      def fetch_updates(marker:, limit:, timeout:, types:)
+        api.get_updates(marker: marker, limit: limit, timeout: timeout, types: types)
+      end
+
+      def advance_marker(result, marker)
+        return marker unless result.is_a?(Hash) && result.key?(:marker)
+
+        result[:marker]
+      end
+
+      def deliver_updates(result, &block)
+        updates = result.is_a?(Hash) ? (result[:updates] || []) : []
+        updates.each { |u| block.call(u) }
+      end
+
+      def handle_poll_error(error, backoff)
+        if (cb = options[:on_error])
+          cb.call(error)
+        elsif (log = options[:logger]) && log.respond_to?(:warn)
+          log.warn("#{error.class}: #{error.message} — retrying in #{backoff}s")
+        end
+        sleeper = options[:sleep] || ->(duration) { Kernel.sleep(duration) }
+        sleeper.call(backoff)
+      end
+
+      def default_options
+        {
+          limit: 100,
+          timeout: 30,
+          types: nil,
+          marker: nil,
+          error_backoff: 3,
+          on_error: nil,
+          logger: nil,
+          sleep: nil
+        }
+      end
+    end
+  end
+end

data/lib/max/bot/configuration.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Max
+  module Bot
+    class Configuration
+      attr_accessor :adapter, :connection_open_timeout, :connection_timeout
+
+      def initialize
+        @adapter = Faraday.default_adapter
+        @connection_open_timeout = 20
+        @connection_timeout = 90
+      end
+    end
+  end
+end

data/lib/max/bot/errors.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Max
+  module Bot
+    class Error < StandardError; end
+
+    class ApiError < Error
+      attr_reader :status, :body
+
+      def initialize(message, status: nil, body: nil)
+        super(message)
+        @status = status
+        @body = body
+      end
+
+      def to_s
+        return super if body.nil? || !body.is_a?(Hash)
+
+        detail = body[:message] || body['message']
+        detail ? "#{super}: #{detail}" : super
+      end
+    end
+  end
+end

data/lib/max/bot/http.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Max
+  module Bot
+    # Low-level HTTP client (Faraday). Use {Api} for public endpoints.
+    class Http
+      attr_reader :token, :base_url
+
+      def initialize(token, base_url, connection: nil)
+        @token = token.to_s
+        @base_url = base_url.to_s.chomp('/')
+        @injected_connection = connection
+      end
+
+      def get(path, query: {})
+        perform(:get, path, query: query)
+      end
+
+      def post(path, query: nil, body: nil)
+        perform(:post, path, query: query, body: body)
+      end
+
+      def delete(path, query: nil)
+        perform(:delete, path, query: query)
+      end
+
+      private
+
+      def perform(method, path, query: nil, body: nil)
+        resp = connection.run_request(method, path, nil, nil) do |req|
+          req.headers['Authorization'] = token
+          if body
+            req.headers['Content-Type'] = 'application/json; charset=utf-8'
+            req.body = ::JSON.generate(body)
+          end
+          req.params.update(query) if query&.any?
+        end
+        Json.decode_response(resp)
+      end
+
+      def connection
+        @injected_connection || @default_connection ||= build_connection
+      end
+
+      def build_connection
+        Faraday.new(url: base_url) do |f|
+          f.adapter Bot.configuration.adapter
+          f.options.timeout = Bot.configuration.connection_timeout
+          f.options.open_timeout = Bot.configuration.connection_open_timeout
+        end
+      end
+    end
+  end
+end

data/lib/max/bot/json.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Max
+  module Bot
+    module Json
+      module_function
+
+      def decode_response(response)
+        raw = response.body.to_s
+        data =
+          if raw.empty?
+            {}
+          else
+            ::JSON.parse(raw)
+          end
+
+        unless response.success?
+          body = data.is_a?(Hash) ? deep_symbolize(data) : data
+          raise ApiError.new("HTTP #{response.status}", status: response.status, body: body)
+        end
+
+        deep_symbolize(data)
+      rescue ::JSON::ParserError => e
+        raise ApiError.new("Invalid JSON: #{e.message}", status: response.status, body: raw)
+      end
+
+      def deep_symbolize(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) { |(k, v), h| h[k.to_sym] = deep_symbolize(v) }
+        when Array
+          obj.map { |e| deep_symbolize(e) }
+        else
+          obj
+        end
+      end
+    end
+  end
+end

data/lib/max/bot/multipart_upload.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'openssl'
+require 'securerandom'
+require 'uri'
+
+module Max
+  module Bot
+    # Multipart +data=@file+ upload to the URL returned by +POST /uploads+.
+    # @see https://dev.max.ru/docs-api/methods/POST/uploads
+    module MultipartUpload
+      module_function
+
+      def post_file(upload_url:, path:, authorization:, filename: nil)
+        raise ArgumentError, 'upload_url must be a non-empty String' if upload_url.to_s.strip.empty?
+
+        filename ||= File.basename(path)
+        filename = filename.to_s.gsub(/["\r\n]/, '_')
+
+        uri = URI(upload_url)
+        boundary = "----maxbot#{SecureRandom.hex(16)}"
+        file_content = File.binread(path)
+        body = +''
+        body << "--#{boundary}\r\n"
+        body << %(Content-Disposition: form-data; name="data"; filename="#{filename}"\r\n)
+        body << "Content-Type: application/octet-stream\r\n\r\n"
+        body << file_content
+        body << "\r\n--#{boundary}--\r\n"
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == 'https')
+        http.open_timeout = Bot.configuration.connection_open_timeout
+        http.read_timeout = Bot.configuration.connection_timeout
+
+        request = Net::HTTP::Post.new(uri.request_uri)
+        request['Content-Type'] = "multipart/form-data; boundary=#{boundary}"
+        request['Authorization'] = authorization.to_s if authorization && !authorization.to_s.empty?
+        request.body = body
+
+        response = http.request(request)
+        unless response.is_a?(Net::HTTPSuccess)
+          raise ApiError.new(
+            "Upload failed HTTP #{response.code}",
+            status: response.code.to_i,
+            body: response.body
+          )
+        end
+
+        response.body.to_s
+      end
+    end
+  end
+end

data/lib/max/bot/update_helpers.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Max
+  module Bot
+    # Convenience parsers aligned with the public MAX Bot API object shapes
+    # (Update → message → body / recipient). Field names may evolve — treat as best-effort.
+    module UpdateHelpers
+      module_function
+
+      def message_created?(update)
+        update.is_a?(Hash) && update[:update_type].to_s == 'message_created'
+      end
+
+      def message_from(update)
+        return unless update.is_a?(Hash)
+
+        update[:message]
+      end
+
+      def message_text(message)
+        return unless message.is_a?(Hash)
+
+        body = message[:body]
+        case body
+        when Hash
+          body[:text] || body[:markdown]
+        when String
+          body
+        end
+      end
+
+      # Returns either [:chat_id, id] or [:user_id, id] for send_message kwargs.
+      def message_destination(message)
+        return unless message.is_a?(Hash)
+
+        recipient = message[:recipient]
+        return unless recipient.is_a?(Hash)
+
+        if recipient.key?(:chat_id) && !recipient[:chat_id].nil?
+          [:chat_id, recipient[:chat_id]]
+        elsif recipient.key?(:user_id) && !recipient[:user_id].nil?
+          [:user_id, recipient[:user_id]]
+        end
+      end
+    end
+  end
+end

data/lib/max/bot/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Max
+  module Bot
+    VERSION = '0.2.0'
+  end
+end

data/lib/max/bot/webhook.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Max
+  module Bot
+    # Helpers for HTTPS webhook endpoints (POST body = Update JSON).
+    # Optional header X-Max-Bot-Api-Secret when a subscription secret is set.
+    # https://dev.max.ru/docs-api/methods/POST/subscriptions
+    module Webhook
+      SECRET_HEADER = 'X-Max-Bot-Api-Secret'
+
+      module_function
+
+      def secret_valid?(header_value, expected_secret)
+        return true if expected_secret.nil? || expected_secret.to_s.empty?
+
+        a = header_value.to_s
+        b = expected_secret.to_s
+        return false unless a.bytesize == b.bytesize
+
+        l = 0
+        a.bytes.zip(b.bytes) { |x, y| l |= x ^ y }
+        l.zero?
+      end
+
+      def extract_secret_header(env)
+        return unless env.is_a?(Hash)
+
+        env['HTTP_X_MAX_BOT_API_SECRET'] || env[SECRET_HEADER]
+      end
+
+      def parse_json(body)
+        return {} if body.nil? || body.to_s.empty?
+
+        JSON.parse(body.to_s, symbolize_names: true)
+      end
+    end
+  end
+end

data/lib/max/bot.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'faraday'
+
+require_relative 'bot/version'
+require_relative 'bot/configuration'
+require_relative 'bot/errors'
+require_relative 'bot/json'
+require_relative 'bot/http'
+require_relative 'bot/attachments'
+require_relative 'bot/multipart_upload'
+require_relative 'bot/api/request_builders'
+require_relative 'bot/api'
+require_relative 'bot/client'
+require_relative 'bot/webhook'
+require_relative 'bot/update_helpers'
+
+module Max
+  module Bot
+    class << self
+      attr_writer :configuration
+
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield configuration
+      end
+    end
+  end
+end

data/lib/max_bot.rb

@@ -1,3 +1,3 @@
-module MaxBot
+# frozen_string_literal: true
 
-end
+require_relative 'max/bot'

data/test/max/bot/api/request_builders_test.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+module Max
+  module Bot
+    class ApiRequestBuildersTest < Minitest::Test
+      def test_combine_attachments_order
+        a = { type: 'share', payload: { url: 'https://a' } }
+        b = { type: 'image', payload: { token: 't' } }
+        out = Api::RequestBuilders.combine_attachments(a, [b])
+        assert_equal %w[share image], out.map { |h| h[:type] }
+      end
+
+      def test_combine_attachments_rejects_invalid_attachment
+        err = assert_raises(ArgumentError) do
+          Api::RequestBuilders.combine_attachments('bad', nil)
+        end
+        assert_match(/attachment:/, err.message)
+      end
+
+      def test_updates_query_types_csv
+        q = Api::RequestBuilders.updates_query(marker: 5, limit: 10, timeout: 20, types: %w[a b])
+        assert_equal 5, q[:marker]
+        assert_equal 10, q[:limit]
+        assert_equal 20, q[:timeout]
+        assert_equal 'a,b', q[:types]
+      end
+
+      def test_updates_query_omits_empty_types
+        q = Api::RequestBuilders.updates_query(marker: nil, limit: nil, timeout: nil, types: [])
+        refute q.key?(:types)
+      end
+
+      def test_subscription_body_optional_fields
+        b = Api::RequestBuilders.subscription_body(url: 'https://x', update_types: %w[a], secret: 's')
+        assert_equal 'https://x', b[:url]
+        assert_equal %w[a], b[:update_types]
+        assert_equal 's', b[:secret]
+      end
+
+      def test_media_attachment_from_upload_image
+        att = Api::RequestBuilders.media_attachment_from_upload(:image, token: 'tok', url: 'https://u')
+        assert_equal 'image', att[:type]
+        assert_equal 'tok', att[:payload][:token]
+        assert_equal 'https://u', att[:payload][:url]
+      end
+
+      def test_media_attachment_unknown_type
+        assert_raises(ArgumentError) do
+          Api::RequestBuilders.media_attachment_from_upload(:unknown, token: 'x')
+        end
+      end
+    end
+  end
+end