max_bot 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9798290fd20acc0ea20843c2a0f22175d8c2d61418eb213eed1fae1bcda13740
-  data.tar.gz: 9db98a46461b054004627d4e5cdcb87f78ae8dba506197888404a91d75582021
+  metadata.gz: 0c17ffd6dfbd11379193864cf5bfd412ddfa995de84b9e82fa17e547dc7d7225
+  data.tar.gz: d831baa3f7bb717c2ad95acb41536c8925e43a62539ee6d784aa1c29cfc74254
 SHA512:
-  metadata.gz: fd5e1fe41c190e5674102629b50a1c957dcb70fbd1fb41e554a7a3ee00fa76dbe3a691d3823e1e612c60d88f9a6dbca417c527df78a21deef76419855b449e2f
-  data.tar.gz: 60beb4d85f30c007a53a73b2710a71661d17670f15f6e1839dcbd8ee3cdffa5e472280185d7f43d892bc20944b53f9c5d7a3627e80bbb6b2162702dc5cc4653f
+  metadata.gz: 8b5dbbc7d6f38b01206430efc691ace09c68be6d0ee1a81322816ba5c4dde280ac338ab655cc4fd5d5f114fbe58938331150550df7be83462cd7776efc8bc6da
+  data.tar.gz: ed9cc5d5c132d6e4d8f22bc6bf7dbd16486ce4533bb659049053026a73725c54505f6de1bd1e23011b041a14939900d50cb75a126f46ad0d82f1b9575a312a1a

data/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+## 0.2.0
+
+Changes in **0.2.0** compared to **0.1.1** are described below in **English** and **Russian**.
+
+### English
+
+#### API client & HTTP
+
+- Modular stack: `Max::Bot::Http` (Faraday) and `Max::Bot::Json` for JSON parsing and `deep_symbolize`.
+- `Max::Bot::Api`: messages (`POST /messages`), long polling (`GET /updates`), subscriptions & webhooks (`GET` / `POST` / `DELETE /subscriptions`), chats (`GET /chats`), uploads (`POST /uploads` + multipart upload to the returned URL).
+- `Authorization` header on requests; JSON body for `POST /messages` without conflicting `url_encoded` middleware.
+- Optional `http:` injection into `Api.new` for tests and stubs.
+- HTTP failures: `Max::Bot::ApiError` (`#status`, `#body`, richer `#to_s` when the body includes `message`).
+
+#### Messages & attachments
+
+- `send_message` with `chat_id` / `user_id`, `format`, `notify`, `link`, `disable_link_preview`.
+- `attachment:` (single Hash or Array) and `attachments:`; merged into one list in order.
+- `Max::Bot::Attachments`: `image`, `video`, `audio`, `file`, `sticker`, `contact`, `inline_keyboard` / `keyboard`, `location`, `share`, button helpers (`callback_button`, `link_button`, etc.), `raw`.
+- `create_upload`, `upload_file`, `send_media` for media per [upload docs](https://dev.max.ru/docs-api/methods/POST/uploads).
+- `Max::Bot::MultipartUpload`: `multipart/form-data` via stdlib `Net::HTTP`.
+
+#### Long polling & webhooks
+
+- `Max::Bot::Client`: `GET /updates` loop, marker, `types` / `limit` / `timeout`, retries on errors (`error_backoff`, `on_error`, `logger`), re-raises `Interrupt`.
+- `Max::Bot::Webhook`: `X-Max-Bot-Api-Secret` header, JSON body parsing.
+- `Max::Bot::UpdateHelpers`: `message_created`, message text, recipient (`chat_id` / `user_id`).
+
+#### Gem infrastructure
+
+- Entrypoint `require "max_bot"` → `lib/max/bot.rb`; `Max::Bot.configure` (Faraday timeouts, adapter).
+- Minitest, default `rake test`, `LICENSE.txt`, `.gitignore`, `examples/polling_bot.rb`.
+- Documentation: `README.md` (Russian), this changelog in English and Russian.
+
+---
+
+### Русский
+
+#### Клиент API и HTTP
+
+- Модульный клиент: `Max::Bot::Http` (Faraday), разбор ответов в `Max::Bot::Json` (JSON + `deep_symbolize`).
+- `Max::Bot::Api`: сообщения (`POST /messages`), long polling (`GET /updates`), подписки и вебхук (`GET`/`POST`/`DELETE /subscriptions`), чаты (`GET /chats`), загрузки (`POST /uploads` + multipart на выданный URL).
+- Заголовок `Authorization` для запросов; JSON-тело для `POST /messages` без конфликта с `url_encoded`.
+- Опциональная инъекция `http:` в `Api.new` для тестов и стабов.
+- Ошибки HTTP: `Max::Bot::ApiError` (`#status`, `#body`, расширенный `#to_s` при поле `message` в теле).
+
+#### Сообщения и вложения
+
+- `send_message` с `chat_id` / `user_id`, `format`, `notify`, `link`, `disable_link_preview`.
+- Параметры `attachment:` (один хэш или массив) и `attachments:`; склейка в один массив.
+- Модуль `Max::Bot::Attachments`: `image`, `video`, `audio`, `file`, `sticker`, `contact`, `inline_keyboard` / `keyboard`, `location`, `share`, кнопки (`callback_button`, `link_button`, и др.), `raw`.
+- `create_upload`, `upload_file`, `send_media` для медиа по [документации загрузок](https://dev.max.ru/docs-api/methods/POST/uploads).
+- `Max::Bot::MultipartUpload` — загрузка `multipart/form-data` через stdlib `Net::HTTP`.
+
+#### Long polling и вебхуки
+
+- `Max::Bot::Client`: цикл `GET /updates`, маркер, `types` / `limit` / `timeout`, повтор при ошибках (`error_backoff`, `on_error`, `logger`), проброс `Interrupt`.
+- `Max::Bot::Webhook`: заголовок `X-Max-Bot-Api-Secret`, разбор JSON тела.
+- `Max::Bot::UpdateHelpers`: разбор `message_created`, текста и адресата из входящих апдейтов.
+
+#### Инфраструктура гема
+
+- Точка входа `require "max_bot"` → `lib/max/bot.rb`; конфигурация `Max::Bot.configure` (таймауты Faraday, адаптер).
+- Minitest, `rake test` по умолчанию, `LICENSE.txt`, `.gitignore`, пример `examples/polling_bot.rb`.
+- Документация: `README.md` (русский), этот changelog — на английском и русском.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) Sergey Syabrenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,242 @@
+# max_bot
+
+Ruby-клиент для Bot API мессенджера **[MAX](https://dev.max.ru/docs-api)**: отправка сообщений, получение обновлений через **long polling** или **HTTPS-вебхуки**, список групповых чатов.
+
+Официальная документация API: [dev.max.ru/docs-api](https://dev.max.ru/docs-api).
+
+История изменений: [CHANGELOG.md](CHANGELOG.md) (английский и русский).
+
+## Требования
+
+- Ruby **≥ 2.5**
+- Токен бота в кабинете MAX (**Чат-боты → Интеграция → Получить токен**)
+
+## Установка
+
+В `Gemfile`:
+
+```ruby
+gem 'max_bot', '~> 0.2'
+```
+
+Локально из этого репозитория:
+
+```bash
+bundle install
+```
+
+## Настройка
+
+По желанию: таймауты и адаптер Faraday.
+
+```ruby
+require 'max_bot'
+
+Max::Bot.configure do |config|
+  config.connection_timeout       = 95   # секунды (должно быть > long-poll timeout)
+  config.connection_open_timeout  = 20
+  config.adapter                  = Faraday.default_adapter
+end
+```
+
+Для `GET /updates` таймаут чтения HTTP должен быть **больше**, чем параметр long polling `timeout` (в `Max::Bot::Client` по умолчанию **30** секунд).
+
+## Запуск бота (long polling)
+
+Long polling рассчитан на **разработку и тесты**. Для продакшена MAX рекомендует **HTTPS-вебхуки** ([POST /subscriptions](https://dev.max.ru/docs-api/methods/POST/subscriptions)).
+
+1. Задайте токен:
+
+   ```bash
+   export MAX_BOT_TOKEN="ваш_токен"
+   ```
+
+2. Из корня репозитория:
+
+   ```bash
+   bundle exec ruby examples/polling_bot.rb
+   ```
+
+Пример делает long polling `GET /updates` с `types: %w[message_created]`, разбирает апдейты через `Max::Bot::UpdateHelpers` и отвечает эхом (`POST /messages`).
+
+### Минимальный цикл polling в своём коде
+
+```ruby
+require 'max_bot'
+
+api = Max::Bot::Api.new(ENV.fetch('MAX_BOT_TOKEN'))
+
+Max::Bot::Client.new(
+  api.token,
+  timeout: 30,
+  limit: 100,
+  types: %w[message_created],
+  error_backoff: 5,
+  logger: Logger.new($stdout) # по желанию
+).run do |update|
+  # update — Hash с символичными ключами (объект Update)
+  next unless Max::Bot::UpdateHelpers.message_created?(update)
+
+  message = Max::Bot::UpdateHelpers.message_from(update)
+  text    = Max::Bot::UpdateHelpers.message_text(message)
+  dest    = Max::Bot::UpdateHelpers.message_destination(message)
+  next if text.to_s.empty? || dest.nil?
+
+  kind, id = dest # :chat_id или :user_id
+  api.send_message("Вы написали: #{text}", kind => id)
+end
+```
+
+**Через метод класса:**
+
+```ruby
+Max::Bot::Client.run(ENV.fetch('MAX_BOT_TOKEN'), timeout: 30) { |u| ... }
+```
+
+При сетевых или API-ошибках клиент **ждёт** `error_backoff` (по умолчанию **3** с) и **повторяет** запрос. `Interrupt` (Ctrl+C) прерывает цикл. Вместо `logger` можно передать **`on_error: ->(e) { ... }`**.
+
+## Отправка сообщений
+
+```ruby
+api = Max::Bot::Api.new(ENV.fetch('MAX_BOT_TOKEN'))
+
+# Группа / канал
+api.send_message('Привет', chat_id: 123)
+
+# Личка
+api.send_message('Привет', user_id: 456)
+
+# Markdown / HTML (см. раздел «Форматирование» в доке API)
+api.send_message('_cursive_', chat_id: 123, format: 'markdown')
+```
+
+`send_message` соответствует **`POST /messages`**: в query — `chat_id` / `user_id`, в теле — JSON. Подробнее: [Отправить сообщение](https://dev.max.ru/docs-api/methods/POST/messages).
+
+### Вложения (`Max::Bot::Attachments`)
+
+Типизированные хелперы под API: **image**, **video**, **audio**, **file**, **sticker**, **contact**, **inline_keyboard**, **location**, **share**. Примеры клавиатуры — в [документации MAX](https://dev.max.ru/docs-api).
+
+```ruby
+api.send_message(
+  'Выберите',
+  chat_id: chat_id,
+  attachment: Max::Bot::Attachments.inline_keyboard([
+    [
+      Max::Bot::Attachments.callback_button('A', 'choice_a'),
+      Max::Bot::Attachments.callback_button('B', 'choice_b')
+    ],
+    [Max::Bot::Attachments.link_button('Документация', 'https://dev.max.ru/docs-api')]
+  ])
+)
+
+api.send_message(
+  'Тут',
+  user_id: user_id,
+  attachments: [
+    Max::Bot::Attachments.location(latitude: 55.75, longitude: 37.61),
+    Max::Bot::Attachments.share(url: 'https://example.com/article')
+  ]
+)
+
+api.send_message('Стикер', chat_id: cid, attachment: Max::Bot::Attachments.sticker(code: 'код_стикера'))
+```
+
+Можно передать **`attachment:`** (один Hash или массив) и/или **`attachments:`** — порядок сохраняется.
+
+### Загрузка медиа (`POST /uploads`)
+
+Для **image**, **video**, **audio**, **file**: слот загрузки → `multipart/form-data` на выданный URL → в сообщении использовать **token** из ответа. См. [Загрузка файлов](https://dev.max.ru/docs-api/methods/POST/uploads).
+
+```ruby
+# Низкоуровнево
+slot = api.create_upload(type: :video) # => { url: "https://..." } и др. поля
+meta = api.upload_file(type: :video, path: '/path/to/clip.mp4')
+api.send_message('Видео', chat_id: id, attachment: Max::Bot::Attachments.video(token: meta[:token]))
+
+# Одной строкой
+api.send_media(type: :image, path: '/path/to/photo.jpg', text: 'Фото', chat_id: id)
+```
+
+После загрузки больших файлов перед `POST /messages` может понадобиться пауза (в доке — ошибка **attachment.not.ready**).
+
+## Вебхуки (продакшен)
+
+1. Поднимите **HTTPS**-endpoint (порт **443**, валидная цепочка TLS — см. требования MAX).
+
+2. Подписка:
+
+   ```ruby
+   api.set_webhook(
+     url: 'https://your.domain/max/webhook',
+     update_types: %w[message_created bot_started],
+     secret: 'your_secret' # по желанию, 5–256 символов [a-zA-Z0-9_-]
+   )
+   ```
+
+3. В веб-приложении проверьте секретный заголовок и разберите JSON:
+
+   ```ruby
+   require 'max_bot'
+
+   secret = ENV.fetch('WEBHOOK_SECRET')
+   header = Max::Bot::Webhook.extract_secret_header(env) # Rack env
+   halt 401 unless Max::Bot::Webhook.secret_valid?(header, secret)
+
+   update = Max::Bot::Webhook.parse_json(request_body)
+   # обработка update (тот же формат, что и при long polling)
+   ```
+
+Заголовок: **`X-Max-Bot-Api-Secret`**. Подробнее: [Подписка на обновления](https://dev.max.ru/docs-api/methods/POST/subscriptions).
+
+4. Отключение вебхука (снова доступен long polling):
+
+   ```ruby
+   api.delete_webhook('https://your.domain/max/webhook')
+   ```
+
+## Другие методы API
+
+| Метод | HTTP |
+|--------|------|
+| `api.chats` | [GET /chats](https://dev.max.ru/docs-api/methods/GET/chats) |
+| `api.subscriptions` | [GET /subscriptions](https://dev.max.ru/docs-api/methods/GET/subscriptions) |
+
+## Ошибки
+
+Неуспешные HTTP-ответы вызывают **`Max::Bot::ApiError`**: `#status`, `#body` (Hash с символичными ключами, если пришёл JSON).
+
+## Структура библиотеки
+
+Типичный layout RubyGem: файл гема совпадает с именем, код — в `lib/max/bot/`.
+
+| Путь | Назначение |
+|------|------------|
+| `lib/max_bot.rb` | `require "max_bot"` → подключает `max/bot` |
+| `lib/max/bot.rb` | Загрузка зависимостей, `Max::Bot.configure` |
+| `lib/max/bot/api.rb` | Публичные методы Bot API |
+| `lib/max/bot/api/request_builders.rb` | Сборка query/body для {Api} |
+| `lib/max/bot/http.rb` | Faraday, JSON-тело, заголовок `Authorization` |
+| `lib/max/bot/json.rb` | Разбор ответа, `deep_symbolize` |
+| `lib/max/bot/attachments.rb` | Билдеры вложений и клавиатуры |
+| `lib/max/bot/multipart_upload.rb` | Multipart-загрузка на CDN-URL |
+| `lib/max/bot/client.rb` | Цикл long polling `GET /updates` |
+
+Для кастомного транспорта или стабов можно подставить объект как **`Max::Bot::Http`**:
+
+```ruby
+api = Max::Bot::Api.new(token, http: my_http_client)
+```
+
+В тестах: **`Max::Bot::Client.new(..., api: fake_api, sleep: ->(_) {})`** — без реального `sleep` и с подменённым API.
+
+## Разработка
+
+```bash
+bundle install
+bundle exec rake test    # задача по умолчанию
+gem build max_bot.gemspec
+```
+
+## Лицензия
+
+MIT — см. [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.warning = true
+end
+
+task default: :test

data/examples/polling_bot.rb

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Run from the repository root:
+#   bundle install
+#   export MAX_BOT_TOKEN="your_token"
+#   bundle exec ruby examples/polling_bot.rb
+
+require 'bundler/setup'
+require 'logger'
+require 'max_bot'
+
+token = ENV['MAX_BOT_TOKEN']
+abort 'Set MAX_BOT_TOKEN from the MAX platform (Chat bots → Integration → token).' if token.to_s.strip.empty?
+
+logger = Logger.new($stdout)
+logger.level = Logger::INFO
+
+Max::Bot.configure do |c|
+  c.connection_timeout = 95
+  c.connection_open_timeout = 20
+end
+
+api = Max::Bot::Api.new(token)
+
+Max::Bot::Client.new(
+  token,
+  timeout: 30,
+  limit: 100,
+  types: %w[message_created],
+  logger: logger,
+  error_backoff: 5
+).run do |update|
+  logger.debug(update.inspect)
+  next unless Max::Bot::UpdateHelpers.message_created?(update)
+
+  message = Max::Bot::UpdateHelpers.message_from(update)
+  text = Max::Bot::UpdateHelpers.message_text(message)
+  dest = Max::Bot::UpdateHelpers.message_destination(message)
+  next if text.to_s.empty? || dest.nil?
+
+  kind, id = dest
+  api.send_message("Echo: #{text}", kind => id)
+rescue Max::Bot::ApiError => e
+  logger.error("API error #{e.status}: #{e}")
+end

data/lib/max/bot/api/request_builders.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Max
+  module Bot
+    class Api
+      # Query/body assembly for {Api} — keeps the public class thin and readable.
+      module RequestBuilders
+        class << self
+          def combine_attachments(attachment, attachments)
+            parts = []
+            append_attachment_slot!(parts, attachment, :attachment)
+            append_attachment_slot!(parts, attachments, :attachments)
+            return if parts.empty?
+
+            parts
+          end
+
+          def message_query(chat_id:, user_id:, disable_link_preview:)
+            q = {}
+            q[:chat_id] = chat_id unless chat_id.nil?
+            q[:user_id] = user_id unless user_id.nil?
+            q[:disable_link_preview] = disable_link_preview unless disable_link_preview.nil?
+            q
+          end
+
+          def message_body(text:, attachments:, format:, notify:, link:)
+            body = {}
+            body[:text] = text unless text.nil?
+            body[:attachments] = attachments unless attachments.nil?
+            body[:format] = format if format
+            body[:notify] = notify unless notify.nil?
+            body[:link] = link unless link.nil?
+            body
+          end
+
+          def updates_query(marker:, limit:, timeout:, types:)
+            query = {}
+            query[:marker] = marker unless marker.nil?
+            query[:limit] = limit unless limit.nil?
+            query[:timeout] = timeout unless timeout.nil?
+            if types
+              list = Array(types).compact
+              query[:types] = list.join(',') unless list.empty?
+            end
+            query
+          end
+
+          def subscription_body(url:, update_types:, secret:)
+            body = { url: url }
+            body[:update_types] = update_types if update_types
+            body[:secret] = secret if secret
+            body
+          end
+
+          def chats_query(count:, marker:)
+            query = {}
+            query[:count] = count unless count.nil?
+            query[:marker] = marker unless marker.nil?
+            query
+          end
+
+          def media_attachment_from_upload(type, data)
+            t = type.to_s
+            payload = {}
+            payload[:token] = data[:token] if data.key?(:token)
+            payload[:url] = data[:url] if data.key?(:url)
+            payload[:photos] = data[:photos] if data.key?(:photos)
+
+            case t
+            when 'image' then Attachments.image(**payload)
+            when 'video' then Attachments.video(**payload)
+            when 'audio' then Attachments.audio(**payload)
+            when 'file' then Attachments.file(**payload)
+            else
+              raise ArgumentError, "unsupported media type: #{type}"
+            end
+          end
+
+          private
+
+          def append_attachment_slot!(parts, value, role)
+            case value
+            when Array
+              parts.concat(value)
+            when Hash
+              parts << value
+            when nil
+              # skip
+            else
+              label = role == :attachment ? 'attachment:' : 'attachments:'
+              raise ArgumentError, "#{label} must be a Hash or Array of Hash"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/max/bot/api.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Max
+  module Bot
+    # HTTP facade for the MAX Bot API (+platform-api.max.ru+).
+    #
+    # @see https://dev.max.ru/docs-api
+    class Api
+      DEFAULT_URL = 'https://platform-api.max.ru'
+
+      UPLOAD_TYPES = %w[image video audio file].freeze
+
+      attr_reader :token, :base_url, :http
+
+      def initialize(token, url: DEFAULT_URL, http: nil)
+        raise ArgumentError, 'token must be a non-empty String' if token.nil? || token.to_s.strip.empty?
+
+        @token = token.to_s
+        @base_url = url.to_s.chomp('/')
+        @http = http || Http.new(@token, @base_url)
+      end
+
+      # --- Messages -------------------------------------------------
+
+      # POST /messages — https://dev.max.ru/docs-api/methods/POST/messages
+      def send_message(text = nil, chat_id: nil, user_id: nil, attachment: nil, attachments: nil, format: nil,
+                       notify: nil, disable_link_preview: nil, link: nil)
+        assert_recipient!(chat_id, user_id)
+
+        combined = RequestBuilders.combine_attachments(attachment, attachments)
+        assert_message_payload!(text, combined, link)
+
+        http.post(
+          '/messages',
+          query: RequestBuilders.message_query(
+            chat_id: chat_id,
+            user_id: user_id,
+            disable_link_preview: disable_link_preview
+          ),
+          body: RequestBuilders.message_body(
+            text: text,
+            attachments: combined,
+            format: format,
+            notify: notify,
+            link: link
+          )
+        )
+      end
+
+      # POST /uploads — https://dev.max.ru/docs-api/methods/POST/uploads
+      def create_upload(type:)
+        t = normalize_upload_type!(type)
+        http.post('/uploads', query: { type: t })
+      end
+
+      def upload_file(type:, path:, filename: nil)
+        slot = create_upload(type: type)
+        upload_url = slot[:url]
+        if upload_url.nil? || upload_url.to_s.empty?
+          raise ApiError.new('Upload response missing url', body: slot)
+        end
+
+        raw = MultipartUpload.post_file(
+          upload_url: upload_url,
+          path: path,
+          filename: filename,
+          authorization: token
+        )
+
+        parse_upload_response(raw).merge(slot)
+      end
+
+      # Uploads local file then POST /messages with the resulting attachment.
+      def send_media(type:, path:, text: nil, filename: nil, chat_id: nil, user_id: nil, **message_opts)
+        data = upload_file(type: type, path: path, filename: filename)
+        att = RequestBuilders.media_attachment_from_upload(type, data)
+
+        send_message(
+          text,
+          chat_id: chat_id,
+          user_id: user_id,
+          attachment: att,
+          **message_opts
+        )
+      end
+
+      # --- Updates & subscriptions ------------------------------------
+
+      # GET /updates — https://dev.max.ru/docs-api/methods/GET/updates
+      def get_updates(marker: nil, limit: nil, timeout: nil, types: nil)
+        query = RequestBuilders.updates_query(marker: marker, limit: limit, timeout: timeout, types: types)
+        http.get('/updates', query: query)
+      end
+
+      # GET /subscriptions
+      def subscriptions
+        http.get('/subscriptions')
+      end
+
+      # POST /subscriptions — https://dev.max.ru/docs-api/methods/POST/subscriptions
+      def set_webhook(url:, update_types: nil, secret: nil)
+        body = RequestBuilders.subscription_body(url: url, update_types: update_types, secret: secret)
+        http.post('/subscriptions', body: body)
+      end
+
+      # DELETE /subscriptions — https://dev.max.ru/docs-api/methods/DELETE/subscriptions
+      def delete_webhook(webhook_url)
+        http.delete('/subscriptions', query: { url: webhook_url })
+      end
+
+      # --- Chats ----------------------------------------------------
+
+      # GET /chats — https://dev.max.ru/docs-api/methods/GET/chats
+      def chats(count: nil, marker: nil)
+        query = RequestBuilders.chats_query(count: count, marker: marker)
+        http.get('/chats', query: query)
+      end
+
+      private
+
+      def assert_recipient!(chat_id, user_id)
+        return unless chat_id.nil? && user_id.nil?
+
+        raise ArgumentError, 'send_message requires chat_id: or user_id:'
+      end
+
+      def assert_message_payload!(text, combined_attachments, link)
+        return unless text.nil? && combined_attachments.nil? && link.nil?
+
+        raise ArgumentError, 'send_message requires at least one of: text, attachments, attachment, link'
+      end
+
+      def normalize_upload_type!(type)
+        t = type.to_s
+        unless UPLOAD_TYPES.include?(t)
+          raise ArgumentError, "upload type must be one of #{UPLOAD_TYPES.join(', ')}"
+        end
+
+        t
+      end
+
+      def parse_upload_response(raw)
+        stripped = raw.to_s.strip
+        return {} if stripped.empty?
+
+        ::JSON.parse(stripped, symbolize_names: true)
+      end
+    end
+  end
+end