max_api_client 0.1.0

data/lib/max_api_client/client.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module MaxApiClient
+  # HTTP transport client responsible for authenticated API requests.
+  class Client
+    DEFAULT_BASE_URL = "https://platform-api.max.ru"
+    REQUEST_CLASSES = {
+      get: Net::HTTP::Get,
+      post: Net::HTTP::Post,
+      put: Net::HTTP::Put,
+      patch: Net::HTTP::Patch,
+      delete: Net::HTTP::Delete
+    }.freeze
+
+    attr_reader :token, :base_url
+
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(token:, base_url: DEFAULT_BASE_URL, adapter: nil, open_timeout: nil, read_timeout: nil, logger: nil)
+      @token = token
+      @base_url = base_url
+      @adapter = adapter
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      @logger = logger || MaxApiClient.logger
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # rubocop:disable Metrics/ParameterLists
+    def call(method:, path: nil, query: nil, body: nil, path_params: nil, headers: nil, url: nil, raw_body: nil,
+             parse_json: true, open_timeout: nil, read_timeout: nil)
+      request = build_request(
+        method:,
+        path:,
+        query:,
+        body:,
+        path_params:,
+        headers:,
+        url:,
+        raw_body:,
+        parse_json:,
+        open_timeout:,
+        read_timeout:
+      )
+
+      log_debug("max_api_client.request", loggable_request(request))
+
+      response = @adapter ? @adapter.call(request) : perform_request(request)
+
+      log_debug("max_api_client.response", loggable_response(response))
+      response
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    private
+
+    # rubocop:disable Metrics/ParameterLists
+    def build_request(method:, path:, query:, body:, path_params:, headers:, url:, raw_body:, parse_json:,
+                      open_timeout:, read_timeout:)
+      {
+        method: method.to_sym,
+        url: build_url(path:, path_params:, query:, url:),
+        path: path,
+        path_params: path_params,
+        query: query,
+        body: body,
+        raw_body: raw_body,
+        headers: default_headers(headers, body:, raw_body:),
+        parse_json: parse_json,
+        open_timeout: open_timeout,
+        read_timeout: read_timeout
+      }
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # rubocop:disable Metrics/AbcSize
+    def build_url(path:, path_params:, query:, url:)
+      uri = if url
+              URI(url)
+            else
+              URI.join(base_url.end_with?("/") ? base_url : "#{base_url}/", expand_path(path.to_s, path_params))
+            end
+
+      params = URI.decode_www_form(String(uri.query))
+      query.to_h.each do |key, value|
+        next if value.nil? || value == false
+
+        params << [key.to_s, value.to_s]
+      end
+      uri.query = params.empty? ? nil : URI.encode_www_form(params)
+      uri
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    def expand_path(path, path_params)
+      path_params.to_h.each_with_object(path.dup) do |(key, value), expanded|
+        expanded.gsub!("{#{key}}", URI.encode_www_form_component(value.to_s))
+      end
+    end
+
+    def default_headers(headers, body:, raw_body:)
+      {
+        "Authorization" => token.to_s
+      }.tap do |result|
+        result["Content-Type"] = "application/json" if body && raw_body.nil?
+        result.merge!(headers.to_h)
+      end
+    end
+
+    def perform_request(request)
+      uri = request.fetch(:url)
+      response = configured_http(
+        uri,
+        open_timeout: request[:open_timeout],
+        read_timeout: request[:read_timeout]
+      ).request(build_http_request(request, uri))
+
+      {
+        status: response.code.to_i,
+        data: parse_response_body(response.body.to_s, parse_json: request[:parse_json]),
+        headers: response.to_hash
+      }
+    end
+
+    def configured_http(uri, open_timeout:, read_timeout:)
+      Net::HTTP.new(uri.host, uri.port).tap do |http|
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = open_timeout || @open_timeout if open_timeout || @open_timeout
+        http.read_timeout = read_timeout || @read_timeout if read_timeout || @read_timeout
+      end
+    end
+
+    def build_http_request(request, uri)
+      REQUEST_CLASSES.fetch(request.fetch(:method)).new(uri).tap do |http_request|
+        request.fetch(:headers).each do |key, value|
+          http_request[key] = value
+        end
+
+        http_request.body = request_body(request)
+      end
+    end
+
+    def request_body(request)
+      return request[:raw_body] if request[:raw_body]
+      return JSON.generate(request[:body]) if request[:body]
+
+      nil
+    end
+
+    def parse_response_body(body, parse_json:)
+      return body unless parse_json
+      return {} if body.empty?
+
+      JSON.parse(body)
+    end
+
+    def log_debug(message, payload)
+      @logger&.debug("#{message} #{payload.inspect}")
+    end
+
+    def loggable_request(request)
+      request.merge(
+        headers: mask_headers(request[:headers]),
+        url: request[:url].to_s
+      )
+    end
+
+    def loggable_response(response)
+      response.merge(headers: mask_headers(response[:headers]))
+    end
+
+    def mask_headers(headers)
+      headers.to_h.dup.tap do |result|
+        result["Authorization"] = "[FILTERED]" if result.key?("Authorization")
+        result["authorization"] = "[FILTERED]" if result.key?("authorization")
+      end
+    end
+  end
+end

data/lib/max_api_client/error.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module MaxApiClient
+  # Base error type for gem-specific failures.
+  class Error < StandardError; end
+
+  # Error raised for non-successful API responses.
+  class ApiError < Error
+    attr_reader :status, :response
+
+    def initialize(status, response = {})
+      @status = status
+      @response = response || {}
+      super("#{status}: #{description}")
+    end
+
+    def code
+      response["code"] || response[:code]
+    end
+
+    def description
+      response["message"] || response[:message] || "Unknown API error"
+    end
+  end
+end

data/lib/max_api_client/polling.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module MaxApiClient
+  # Long-polling helper over GET /updates with marker tracking and retries.
+  class Polling
+    DEFAULT_TIMEOUT = 20
+    DEFAULT_RETRY_INTERVAL = 5
+    READ_TIMEOUT_PADDING = 5
+    RETRYABLE_ERRORS = [
+      Net::OpenTimeout,
+      Net::ReadTimeout,
+      EOFError,
+      IOError,
+      SocketError,
+      Errno::ECONNRESET
+    ].freeze
+
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(api, types: [], marker: nil, timeout: DEFAULT_TIMEOUT, retry_interval: DEFAULT_RETRY_INTERVAL,
+                   read_timeout: nil)
+      @api = api
+      @types = types
+      @marker = marker
+      @timeout = timeout
+      @retry_interval = retry_interval
+      @read_timeout = read_timeout || (timeout.to_i + READ_TIMEOUT_PADDING)
+      @stopped = false
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    def each
+      return enum_for(:each) unless block_given?
+
+      until stopped?
+        begin
+          response = fetch_updates
+          @marker = fetch_value(response, :marker)
+
+          Array(fetch_value(response, :updates)).each do |update|
+            break if stopped?
+
+            yield update
+          end
+        rescue *RETRYABLE_ERRORS
+          retry_later
+        rescue ApiError => e
+          raise unless retryable_status?(e.status)
+
+          retry_later
+        end
+      end
+
+      self
+    end
+
+    def stop
+      @stopped = true
+    end
+
+    def stopped?
+      @stopped
+    end
+
+    private
+
+    attr_reader :api, :types, :marker, :timeout, :retry_interval, :read_timeout
+
+    def fetch_updates
+      api.raw.subscriptions.get_updates(
+        types: normalize_types(types),
+        marker:,
+        timeout:,
+        read_timeout:
+      )
+    end
+
+    def retry_later
+      sleep(retry_interval)
+    end
+
+    def retryable_status?(status)
+      status == 429 || status >= 500
+    end
+
+    def fetch_value(hash, key)
+      hash[key] || hash[key.to_s]
+    end
+
+    def normalize_types(value)
+      return value.join(",") if value.is_a?(Array)
+
+      value
+    end
+  end
+end

data/lib/max_api_client/raw_api.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module MaxApiClient
+  # Low-level grouped access to Max Bot API endpoint families.
+  class RawApi < BaseApi
+    attr_reader :client
+
+    def bots
+      @bots ||= build_api(BotsApi)
+    end
+
+    def chats
+      @chats ||= build_api(ChatsApi)
+    end
+
+    def messages
+      @messages ||= build_api(MessagesApi)
+    end
+
+    def subscriptions
+      @subscriptions ||= build_api(SubscriptionsApi)
+    end
+
+    def uploads
+      @uploads ||= build_api(UploadsApi)
+    end
+
+    private
+
+    def build_api(klass)
+      klass.new(client)
+    end
+  end
+
+  # Raw bot profile endpoints.
+  class BotsApi < BaseApi
+    # rubocop:disable Naming/AccessorMethodName
+    def get_my_info
+      get("me")
+    end
+    # rubocop:enable Naming/AccessorMethodName
+
+    def edit_my_info(**extra)
+      patch("me", body: extra)
+    end
+  end
+
+  # Raw chat management endpoints.
+  class ChatsApi < BaseApi
+    def get_all(**extra)
+      get("chats", query: extra)
+    end
+
+    def get_by_id(chat_id:)
+      get("chats/{chat_id}", path_params: { chat_id: })
+    end
+
+    def get_by_link(chat_link:)
+      get("chats/{chat_link}", path_params: { chat_link: })
+    end
+
+    def edit(chat_id:, **extra)
+      patch("chats/{chat_id}", path_params: { chat_id: }, body: extra)
+    end
+
+    def get_chat_membership(chat_id:)
+      get("chats/{chat_id}/members/me", path_params: { chat_id: })
+    end
+
+    def get_chat_admins(chat_id:)
+      get("chats/{chat_id}/members/admins", path_params: { chat_id: })
+    end
+
+    def add_chat_members(chat_id:, user_ids:)
+      post("chats/{chat_id}/members", path_params: { chat_id: }, body: { user_ids: })
+    end
+
+    def get_chat_members(chat_id:, **query)
+      get("chats/{chat_id}/members", path_params: { chat_id: }, query:)
+    end
+
+    def remove_chat_member(chat_id:, user_id:, block: nil)
+      delete("chats/{chat_id}/members", path_params: { chat_id: }, body: compact_nil(user_id:, block:))
+    end
+
+    def get_pinned_message(chat_id:)
+      get("chats/{chat_id}/pin", path_params: { chat_id: })
+    end
+
+    def pin_message(chat_id:, message_id:, notify: nil)
+      put("chats/{chat_id}/pin", path_params: { chat_id: }, body: compact_nil(message_id:, notify:))
+    end
+
+    def unpin_message(chat_id:)
+      delete("chats/{chat_id}/pin", path_params: { chat_id: })
+    end
+
+    def send_action(chat_id:, action:)
+      post("chats/{chat_id}/actions", path_params: { chat_id: }, body: { action: })
+    end
+
+    def leave_chat(chat_id:)
+      delete("chats/{chat_id}/members/me", path_params: { chat_id: })
+    end
+  end
+
+  # Raw message delivery and mutation endpoints.
+  class MessagesApi < BaseApi
+    ATTACHMENT_NOT_READY_CODE = "attachment.not.ready"
+    ATTACHMENT_NOT_READY_DELAY = 1
+
+    def get(**query)
+      super("messages", query:)
+    end
+
+    def get_by_id(message_id:)
+      get("messages/{message_id}", path_params: { message_id: })
+    end
+
+    def send(chat_id: nil, user_id: nil, disable_link_preview: nil, **body)
+      post("messages", query: compact_nil(chat_id:, user_id:, disable_link_preview:), body:)
+    rescue ApiError => e
+      raise unless e.code == ATTACHMENT_NOT_READY_CODE
+
+      sleep(ATTACHMENT_NOT_READY_DELAY)
+      send(chat_id:, user_id:, disable_link_preview:, **body)
+    end
+
+    def edit(message_id:, **body)
+      put("messages", query: { message_id: }, body:)
+    end
+
+    def delete(message_id:)
+      super("messages", query: { message_id: })
+    end
+
+    def answer_on_callback(callback_id:, **body)
+      post("answers", query: { callback_id: }, body:)
+    end
+  end
+
+  # Raw update subscription endpoints.
+  class SubscriptionsApi < BaseApi
+    # rubocop:disable Naming/AccessorMethodName
+    def get_subscriptions
+      get("subscriptions")
+    end
+    # rubocop:enable Naming/AccessorMethodName
+
+    def subscribe(url:, update_types: nil, secret: nil)
+      post("subscriptions", body: compact_nil(url:, update_types:, secret:))
+    end
+
+    def unsubscribe(url:)
+      delete("subscriptions", query: { url: })
+    end
+
+    def get_updates(read_timeout: nil, **query)
+      get("updates", query:, read_timeout:)
+    end
+  end
+
+  # Raw upload URL acquisition endpoints.
+  class UploadsApi < BaseApi
+    def get_upload_url(type:)
+      post("uploads", query: { type: })
+    end
+  end
+end

data/lib/max_api_client/upload.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module MaxApiClient
+  # Upload helper that prepares files and sends them to upload endpoints.
+  class Upload
+    DEFAULT_TIMEOUT = 20
+    BINARY_HEADERS = {
+      "Content-Type" => "application/x-binary; charset=x-user-defined",
+      "X-Uploading-Mode" => "parallel",
+      "Connection" => "keep-alive"
+    }.freeze
+
+    def initialize(api)
+      @api = api
+    end
+
+    def image(source: nil, url: nil, timeout: DEFAULT_TIMEOUT, filename: nil)
+      return { url: } if url
+
+      upload_from_source("image", source, timeout:, filename:)
+    end
+
+    def video(source:, timeout: DEFAULT_TIMEOUT, filename: nil)
+      upload_from_source("video", source, timeout:, filename:)
+    end
+
+    def audio(source:, timeout: DEFAULT_TIMEOUT, filename: nil)
+      upload_from_source("audio", source, timeout:, filename:)
+    end
+
+    def file(source:, timeout: DEFAULT_TIMEOUT, filename: nil)
+      upload_from_source("file", source, timeout:, filename:)
+    end
+
+    private
+
+    attr_reader :api
+
+    def upload_from_source(type, source, timeout:, filename:)
+      upload(type, file_from_source(source, filename:), timeout:)
+    end
+
+    def upload(type, file, timeout:)
+      response = api.raw.uploads.get_upload_url(type:)
+      upload_url = fetch_value(response, :url)
+      token = fetch_value(response, :token)
+
+      return { token: }.tap { upload_binary(upload_url, file, timeout:) } if token
+
+      upload_multipart(upload_url, file, timeout:)
+    end
+
+    # rubocop:disable Metrics/AbcSize
+    def upload_binary(upload_url, file, timeout:)
+      headers = BINARY_HEADERS.merge(
+        "Content-Disposition" => %(attachment; filename="#{file[:filename]}"),
+        "Content-Range" => "bytes 0-#{file[:content].bytesize - 1}/#{file[:content].bytesize}",
+        "X-File-Name" => file[:filename]
+      )
+
+      result = api.client.call(
+        method: :post,
+        url: upload_url,
+        raw_body: file[:content],
+        headers: headers,
+        parse_json: false,
+        open_timeout: timeout,
+        read_timeout: timeout
+      )
+
+      raise ApiError.new(result[:status], { message: result[:data] }) if result[:status] >= 400
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    def upload_multipart(upload_url, file, timeout:)
+      boundary = "----max-api-client-#{SecureRandom.hex(12)}"
+      body = build_multipart_body(boundary, file)
+      headers = {
+        "Content-Type" => "multipart/form-data; boundary=#{boundary}"
+      }
+
+      result = api.client.call(
+        method: :post,
+        url: upload_url,
+        raw_body: body,
+        headers: headers,
+        parse_json: true,
+        open_timeout: timeout,
+        read_timeout: timeout
+      )
+
+      raise ApiError.new(result[:status], result[:data]) if result[:status] >= 400
+
+      result[:data]
+    end
+
+    def build_multipart_body(boundary, file)
+      [
+        "--#{boundary}\r\n",
+        %(Content-Disposition: form-data; name="data"; filename="#{file[:filename]}"\r\n),
+        "Content-Type: application/octet-stream\r\n\r\n",
+        file[:content],
+        "\r\n--#{boundary}--\r\n"
+      ].join
+    end
+
+    def file_from_source(source, filename: nil)
+      raise ArgumentError, "source is required" if source.nil?
+
+      return file_from_path(source, filename:) if source.is_a?(String) && File.file?(source)
+      return file_from_io(source, filename:) if source.respond_to?(:read)
+
+      raise ArgumentError, "source must be a file path or readable IO"
+    end
+
+    def file_from_path(source, filename:)
+      {
+        filename: filename || File.basename(source),
+        content: File.binread(source)
+      }
+    end
+
+    def file_from_io(source, filename:)
+      current_pos = source.pos if source.respond_to?(:pos)
+      source.rewind if source.respond_to?(:rewind)
+      content = source.read
+      source.pos = current_pos if current_pos && source.respond_to?(:pos=)
+
+      {
+        filename: filename || io_filename(source),
+        content:
+      }
+    end
+
+    def io_filename(source)
+      if source.respond_to?(:path) && source.path.is_a?(String)
+        File.basename(source.path)
+      else
+        SecureRandom.uuid
+      end
+    end
+
+    def fetch_value(hash, key)
+      hash[key] || hash[key.to_s]
+    end
+  end
+end

data/lib/max_api_client/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Root namespace for gem version information.
+module MaxApiClient
+  VERSION = "0.1.0"
+end

data/lib/max_api_client.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require "securerandom"
+
+require_relative "max_api_client/version"
+require_relative "max_api_client/error"
+require_relative "max_api_client/client"
+require_relative "max_api_client/base_api"
+require_relative "max_api_client/raw_api"
+require_relative "max_api_client/polling"
+require_relative "max_api_client/attachments"
+require_relative "max_api_client/upload"
+require_relative "max_api_client/api"
+
+# Root namespace for the Max Bot API Ruby client.
+module MaxApiClient
+  class << self
+    attr_accessor :logger
+  end
+end