max_api_client 0.1.0

data/README.md

@@ -0,0 +1,272 @@
+# max_api_client
+
+Ruby gem для работы с Max Bot API.
+
+## Состояние
+
+Текущая реализация на Ruby включает  API-клиент со следующими возможностями:
+
+- высокоуровневый `MaxApiClient::Api`
+- низкоуровневый `MaxApiClient::RawApi`
+- сгруппированные методы для bot/chat/message/subscription/upload
+- вспомогательные объекты вложений для результатов загрузки
+
+## Установка
+
+Добавьте gem в проект:
+
+```ruby
+# Gemfile
+gem "max_api_client", git: "git@github.com:Ziaw/max_api_client.git"
+```
+
+```bash
+bundle install
+```
+
+## Справочник API
+
+### Методы бота
+
+Методы Ruby, доступные через `MaxApiClient::Api`:
+
+- `get_my_info`
+- `edit_my_info(**extra)`
+- `set_my_commands(commands)`
+- `delete_my_commands`
+
+`set_my_commands(commands)` это короткий хелпер над `edit_my_info(commands: ...)`.
+Он принимает массив команд и отправляет его в поле `commands` профиля бота.
+
+Ожидается массив хэшей с данными команды, например:
+
+```ruby
+api.set_my_commands([
+  { name: "start", description: "Запустить бота" },
+  { name: "help", description: "Показать справку" }
+])
+```
+
+`delete_my_commands` делает то же самое, но передаёт пустой массив и тем самым очищает список команд.
+
+Соответствующие HTTP-маршруты:
+
+- `GET /me`
+- `PATCH /me`
+
+Типовые сценарии:
+
+- получить текущий профиль бота;
+- обновить имя, описание, аватар и команды бота;
+- опубликовать или очистить подсказки команд для пользователей.
+
+### Методы чатов
+
+Методы Ruby, доступные через `MaxApiClient::Api`:
+
+- `get_all_chats(**extra)`
+- `get_chat(chat_id)`
+- `get_chat_by_link(chat_link)`
+- `edit_chat_info(chat_id, **extra)`
+- `get_chat_membership(chat_id)`
+- `get_chat_admins(chat_id)`
+- `add_chat_members(chat_id, user_ids)`
+- `get_chat_members(chat_id, **extra)`
+- `remove_chat_member(chat_id, user_id)`
+- `get_pinned_message(chat_id)`
+- `pin_message(chat_id, message_id, **extra)`
+- `unpin_message(chat_id)`
+- `send_action(chat_id, action)`
+- `leave_chat(chat_id)`
+
+Соответствующие HTTP-маршруты:
+
+- `GET /chats`
+- `GET /chats/{chat_id}`
+- `GET /chats/{chat_link}`
+- `PATCH /chats/{chat_id}`
+- `GET /chats/{chat_id}/members/me`
+- `GET /chats/{chat_id}/members/admins`
+- `POST /chats/{chat_id}/members`
+- `GET /chats/{chat_id}/members`
+- `DELETE /chats/{chat_id}/members`
+- `GET /chats/{chat_id}/pin`
+- `PUT /chats/{chat_id}/pin`
+- `DELETE /chats/{chat_id}/pin`
+- `POST /chats/{chat_id}/actions`
+- `DELETE /chats/{chat_id}/members/me`
+
+Типовые сценарии:
+
+- получить список чатов, доступных боту;
+- найти чат по идентификатору или публичной ссылке;
+- изменить заголовок, иконку и метаданные чата;
+- управлять участниками и администраторами;
+- читать, устанавливать и снимать закреплённые сообщения;
+- отправлять статус набора текста и другие действия отправителя;
+- выходить из чата.
+
+### Методы сообщений
+
+Методы Ruby, доступные через `MaxApiClient::Api`:
+
+- `send_message_to_chat(chat_id, text, **extra)`
+- `send_message_to_user(user_id, text, **extra)`
+- `get_messages(chat_id, **extra)`
+- `get_message(message_id)`
+- `edit_message(message_id, **extra)`
+- `delete_message(message_id, **extra)`
+- `answer_on_callback(callback_id, **extra)`
+
+Соответствующие HTTP-маршруты:
+
+- `POST /messages`
+- `GET /messages`
+- `GET /messages/{message_id}`
+- `PUT /messages`
+- `DELETE /messages`
+- `POST /answers`
+
+Поддерживаемые возможности:
+
+- отправка обычного текста в чат или напрямую пользователю;
+- дополнительный payload для форматирования, reply-ссылок и вложений;
+- редактирование и удаление сообщений;
+- ответы на callback-кнопки;
+- автоматический повтор запроса, если вложение после загрузки ещё не готово.
+
+### Методы подписок
+
+Методы Ruby, доступные через `MaxApiClient::Api`:
+
+- `get_subscriptions`
+- `subscribe(url, update_types: nil, secret: nil)`
+- `unsubscribe(url)`
+- `poll_updates(types = [], marker: nil, timeout: 20, retry_interval: 5, read_timeout: nil, &block)`
+
+Соответствующие HTTP-маршруты:
+
+- `GET /subscriptions`
+- `POST /subscriptions`
+- `DELETE /subscriptions`
+- `GET /updates`
+
+Типовые сценарии:
+
+- получить список активных webhook-подписок бота;
+- создать webhook-подписку на нужные типы обновлений;
+- удалить подписку по URL webhook;
+- использовать polling через `poll_updates`, если webhook не нужен.
+
+Пример long polling:
+
+```ruby
+poller = api.poll_updates(%w[message_created], timeout: 20)
+
+poller.each do |update|
+  puts update["update_type"]
+  # poller.stop if нужно остановить цикл
+end
+```
+
+`poll_updates` автоматически:
+
+- передаёт `marker` между запросами;
+- поднимает HTTP `read_timeout` выше API `timeout`;
+- повторяет запрос после временных сетевых ошибок, `429` и `5xx`.
+
+### Методы загрузки
+
+Методы Ruby, доступные через `MaxApiClient::Api`:
+
+- `upload_image(options)`
+- `upload_video(options)`
+- `upload_audio(options)`
+- `upload_file(options)`
+
+Связанный HTTP-маршрут:
+
+- `POST /uploads`
+
+Вспомогательные классы вложений:
+
+- `ImageAttachment`
+- `VideoAttachment`
+- `AudioAttachment`
+- `FileAttachment`
+- `StickerAttachment`
+- `LocationAttachment`
+- `ShareAttachment`
+
+### Доступ к Raw API
+
+Низкоуровневый доступ через `api.raw` поддерживает:
+
+- `get`
+- `post`
+- `put`
+- `patch`
+- `delete`
+
+## Логирование
+
+Если нужен отладочный лог HTTP-обмена, можно задать глобальный логгер:
+
+```ruby
+MaxApiClient.logger = Logger.new($stdout)
+```
+
+Либо передать логгер в конкретный клиент:
+
+```ruby
+api = MaxApiClient::Api.new(token: ENV.fetch("MAX_BOT_TOKEN"), logger: Logger.new($stdout))
+```
+
+Если логгер задан, клиент пишет в `debug` данные запроса и ответа.
+
+## Разработка
+
+Склонируйте репозиторий и установите зависимости:
+
+```bash
+git clone git@github.com:Ziaw/max_api_client.git
+cd max_api_client
+bundle install
+```
+
+Полезные команды:
+
+```bash
+bundle exec rake test
+bin/console
+```
+
+
+## Релиз
+
+Релиз публикуется через GitHub Releases и GitHub Actions.
+
+Перед релизом:
+
+1. Обновите версию в `lib/max_api_client/version.rb`.
+2. Перенесите изменения из `Unreleased` в `CHANGELOG.md`.
+3. Закоммитьте изменения в `master`.
+
+## Приоритеты реализации
+
+Рекомендуемый порядок развития Ruby-клиента:
+
+1. HTTP-клиент и слой ошибок.
+2. Интерфейс raw-запросов.
+3. Высокоуровневая обёртка `Api` для bot, chat, message и update endpoints.
+4. Механизм загрузки файлов и объекты вложений. (вы находитесь здесь)
+5. Опциональный bot framework с polling, context и middleware.
+
+## Источники
+
+- Официальная документация Max Bot API: <https://dev.max.ru/>
+- TypeScript reference client: <https://github.com/max-messenger/max-bot-api-client-ts>
+
+## Лицензия
+
+Проект распространяется по лицензии MIT. См. [`LICENSE.txt`](./LICENSE.txt).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/max_api_client/api.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module MaxApiClient
+  # High-level convenience wrapper over grouped Max Bot API endpoints.
+  class Api
+    attr_reader :raw, :upload, :client
+
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(token:, base_url: Client::DEFAULT_BASE_URL, adapter: nil, open_timeout: nil, read_timeout: nil,
+                   logger: nil)
+      @client = Client.new(
+        token:,
+        base_url:,
+        adapter:,
+        open_timeout:,
+        read_timeout:,
+        logger:
+      )
+      @raw = RawApi.new(client)
+      @upload = Upload.new(self)
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # rubocop:disable Naming/AccessorMethodName
+    def get_my_info
+      raw.bots.get_my_info
+    end
+    # rubocop:enable Naming/AccessorMethodName
+
+    def edit_my_info(**extra)
+      raw.bots.edit_my_info(**extra)
+    end
+
+    # rubocop:disable Naming/AccessorMethodName
+    def set_my_commands(commands)
+      edit_my_info(commands:)
+    end
+    # rubocop:enable Naming/AccessorMethodName
+
+    def delete_my_commands
+      edit_my_info(commands: [])
+    end
+
+    def get_all_chats(**extra)
+      raw.chats.get_all(**extra)
+    end
+
+    def get_chat(chat_id)
+      raw.chats.get_by_id(chat_id:)
+    end
+
+    def get_chat_by_link(chat_link)
+      raw.chats.get_by_link(chat_link:)
+    end
+
+    def edit_chat_info(chat_id, **extra)
+      raw.chats.edit(chat_id:, **extra)
+    end
+
+    def get_chat_membership(chat_id)
+      raw.chats.get_chat_membership(chat_id:)
+    end
+
+    def get_chat_admins(chat_id)
+      raw.chats.get_chat_admins(chat_id:)
+    end
+
+    def add_chat_members(chat_id, user_ids)
+      raw.chats.add_chat_members(chat_id:, user_ids:)
+    end
+
+    def get_chat_members(chat_id, **extra)
+      raw.chats.get_chat_members(chat_id:, **csv_query(extra, :user_ids))
+    end
+
+    def remove_chat_member(chat_id, user_id, block: nil)
+      raw.chats.remove_chat_member(chat_id:, user_id:, block:)
+    end
+
+    def get_pinned_message(chat_id)
+      raw.chats.get_pinned_message(chat_id:)
+    end
+
+    def pin_message(chat_id, message_id, **extra)
+      raw.chats.pin_message(chat_id:, message_id:, notify: extra[:notify])
+    end
+
+    def unpin_message(chat_id)
+      raw.chats.unpin_message(chat_id:)
+    end
+
+    def send_action(chat_id, action)
+      raw.chats.send_action(chat_id:, action:)
+    end
+
+    def leave_chat(chat_id)
+      raw.chats.leave_chat(chat_id:)
+    end
+
+    def send_message_to_chat(chat_id, text, **extra)
+      message_from(raw.messages.send(chat_id:, text:, **extra))
+    end
+
+    def send_message_to_user(user_id, text, **extra)
+      message_from(raw.messages.send(user_id:, text:, **extra))
+    end
+
+    def get_messages(chat_id, **extra)
+      raw.messages.get(chat_id:, **csv_query(extra, :message_ids))
+    end
+
+    def get_message(message_id)
+      raw.messages.get_by_id(message_id:)
+    end
+
+    def edit_message(message_id, **extra)
+      raw.messages.edit(message_id:, **extra)
+    end
+
+    def delete_message(message_id, **extra)
+      raw.messages.delete(message_id:, **extra)
+    end
+
+    def answer_on_callback(callback_id, **extra)
+      raw.messages.answer_on_callback(callback_id:, **extra)
+    end
+
+    # rubocop:disable Naming/AccessorMethodName
+    def get_subscriptions
+      raw.subscriptions.get_subscriptions
+    end
+    # rubocop:enable Naming/AccessorMethodName
+
+    def subscribe(url, update_types: nil, secret: nil)
+      raw.subscriptions.subscribe(url:, update_types:, secret:)
+    end
+
+    def unsubscribe(url)
+      raw.subscriptions.unsubscribe(url:)
+    end
+
+    def poll_updates(types = [], marker: nil, timeout: Polling::DEFAULT_TIMEOUT,
+                     retry_interval: Polling::DEFAULT_RETRY_INTERVAL, read_timeout: nil, &block)
+      poller = Polling.new(
+        self,
+        types:,
+        marker:,
+        timeout:,
+        retry_interval:,
+        read_timeout:
+      )
+
+      return poller.each unless block
+
+      poller.each(&block)
+    end
+
+    def upload_image(options)
+      data = upload.image(**options)
+      ImageAttachment.new(token: data[:token], photos: data[:photos], url: data[:url] || data["url"])
+    end
+
+    def upload_video(options)
+      data = upload.video(**options)
+      VideoAttachment.new(token: data[:token] || data["token"])
+    end
+
+    def upload_audio(options)
+      data = upload.audio(**options)
+      AudioAttachment.new(token: data[:token] || data["token"])
+    end
+
+    def upload_file(options)
+      data = upload.file(**options)
+      FileAttachment.new(token: data[:token] || data["token"])
+    end
+
+    private
+
+    def normalize_types(types)
+      return types unless types.is_a?(Array)
+
+      types.join(",")
+    end
+
+    def csv_query(query, key)
+      query.merge(key => normalize_types(query[key]))
+    end
+
+    def message_from(response)
+      response.fetch("message") { response.fetch(:message) }
+    end
+  end
+end

data/lib/max_api_client/attachments.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module MaxApiClient
+  # Base type for all outgoing attachment payload wrappers.
+  class Attachment
+    def to_h
+      raise NotImplementedError, "#{self.class} must implement #to_h"
+    end
+  end
+
+  # Shared attachment implementation for upload-backed media objects.
+  class MediaAttachment < Attachment
+    attr_reader :token
+
+    def initialize(token: nil)
+      super()
+      @token = token
+    end
+
+    def payload
+      { token: token }
+    end
+  end
+
+  # Attachment wrapper for uploaded or remote images.
+  class ImageAttachment < MediaAttachment
+    attr_reader :photos, :url
+
+    def initialize(token: nil, photos: nil, url: nil)
+      super(token:)
+      @photos = photos
+      @url = url
+    end
+
+    def payload
+      return { token: token } if token
+      return { url: url } if url
+
+      { photos: photos }
+    end
+
+    def to_h
+      { type: "image", payload: }
+    end
+  end
+
+  # Attachment wrapper for uploaded videos.
+  class VideoAttachment < MediaAttachment
+    def to_h
+      { type: "video", payload: }
+    end
+  end
+
+  # Attachment wrapper for uploaded audio files.
+  class AudioAttachment < MediaAttachment
+    def to_h
+      { type: "audio", payload: }
+    end
+  end
+
+  # Attachment wrapper for generic uploaded files.
+  class FileAttachment < MediaAttachment
+    def to_h
+      { type: "file", payload: }
+    end
+  end
+
+  # Attachment wrapper for sticker references.
+  class StickerAttachment < Attachment
+    attr_reader :code
+
+    def initialize(code:)
+      super()
+      @code = code
+    end
+
+    def to_h
+      { type: "sticker", payload: { code: } }
+    end
+  end
+
+  # Attachment wrapper for geo coordinates.
+  class LocationAttachment < Attachment
+    attr_reader :longitude, :latitude
+
+    def initialize(lon:, lat:)
+      super()
+      @longitude = lon
+      @latitude = lat
+    end
+
+    def to_h
+      { type: "location", latitude:, longitude: }
+    end
+  end
+
+  # Attachment wrapper for shared links or tokens.
+  class ShareAttachment < Attachment
+    attr_reader :url, :token
+
+    def initialize(url: nil, token: nil)
+      super()
+      @url = url
+      @token = token
+    end
+
+    def to_h
+      { type: "share", payload: { url:, token: } }
+    end
+  end
+end

data/lib/max_api_client/base_api.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module MaxApiClient
+  # Shared HTTP helper for raw API groups.
+  class BaseApi
+    HTTP_METHODS = %i[get post put patch delete].freeze
+
+    def initialize(client)
+      @client = client
+    end
+
+    HTTP_METHODS.each do |name|
+      define_method(name) do |path, **options|
+        call_api(name, path, **options)
+      end
+    end
+
+    private
+
+    attr_reader :client
+
+    def call_api(http_method, path, **options)
+      result = client.call(
+        method: http_method,
+        path:,
+        **options
+      )
+      raise ApiError.new(result[:status], result[:data]) unless result[:status] == 200
+
+      result[:data]
+    end
+
+    def compact_nil(hash)
+      hash.compact
+    end
+  end
+end