max_bot_api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3513bab6b7e83202a50274c5eba30655b5825bc56a5a6e26de78eae549e0e38f
+  data.tar.gz: 0f97c303649e2c8db1d54f64af70fffc99a030ab95866d089094cff533a4e98c
+SHA512:
+  metadata.gz: 0d9ee73288cf706f2ba868e82bab3456bc6f7857d8b1a46cc8cf6fa273d2d0d4e800c93f62bce64f6bb822231385c4166d160fb6c13300649a1dcd18cf80a217
+  data.tar.gz: e4f90c9ccbc8ddaf116922c1dc3f6b7c83e4d261e20237e83b3d593703fd709898aa2ae201bfced427279c3b3378c318635e0fcbdf2c0b9721448f25a51962ed

data/README.md

@@ -0,0 +1,168 @@
+# MaxBotApi Ruby Client
+
+Ruby client for the MAX Bot API, mirroring the official Go client.
+
+## Installation
+
+```bash
+gem install max_bot_api
+```
+
+Or in your Gemfile:
+
+```ruby
+gem "max_bot_api"
+```
+
+## Quick start
+
+```ruby
+require "max_bot_api"
+
+client = MaxBotApi::Client.new(token: ENV.fetch("TOKEN"))
+
+me = client.bots.get_bot
+puts "Bot: #{me[:name]}"
+
+client.messages.send(
+  MaxBotApi::Builders::MessageBuilder.new
+    .set_chat(12345)
+    .set_text("Hello from Ruby")
+)
+```
+
+## Features
+
+- Full API coverage: Bots, Chats, Messages, Subscriptions, Uploads, Debugs.
+- Builder helpers for messages and keyboards.
+- Long polling updates with retry and backoff.
+- Webhook parsing helper.
+- Upload helpers for files, photos, audio, video.
+
+## Configuration
+
+```ruby
+client = MaxBotApi::Client.new(
+  token: ENV.fetch("TOKEN"),
+  base_url: "https://botapi.max.ru/",
+  version: "1.2.5"
+)
+```
+
+Notes:
+
+- The client uses `Authorization: <token>` (no `Bearer`).
+- Every request includes `v=<version>` query param.
+
+## Common tasks
+
+### Send messages
+
+```ruby
+message = MaxBotApi::Builders::MessageBuilder.new
+  .set_chat(12345)
+  .set_text("Hello, chat!")
+
+client.messages.send(message)
+```
+
+### Send with result
+
+```ruby
+message = MaxBotApi::Builders::MessageBuilder.new
+  .set_chat(12345)
+  .set_text("Hello, chat!")
+
+sent = client.messages.send_with_result(message)
+puts sent[:body][:mid]
+```
+
+### Reply to a message
+
+```ruby
+message = MaxBotApi::Builders::MessageBuilder.new
+  .set_chat(12345)
+  .set_reply("Thanks!", "mid123")
+
+client.messages.send(message)
+```
+
+### Long polling updates
+
+```ruby
+client.each_update do |update|
+  case update[:update_type]
+  when "message_created"
+    text = update.dig(:message, :body, :text)
+    puts "New message: #{text}"
+  end
+end
+```
+
+### Webhook parsing
+
+```ruby
+body = request.body.read
+update = client.parse_webhook(body)
+```
+
+## Builders
+
+### Keyboard
+
+```ruby
+keyboard = client.messages.new_keyboard_builder
+keyboard
+  .add_row
+  .add_geolocation("Share location", true)
+  .add_contact("Share contact")
+
+keyboard
+  .add_row
+  .add_link("Open MAX", "positive", "https://max.ru")
+  .add_callback("Audio", "negative", "audio")
+
+message = MaxBotApi::Builders::MessageBuilder.new
+  .set_chat(12345)
+  .add_keyboard(keyboard)
+  .set_text("Choose an action")
+
+client.messages.send(message)
+```
+
+### Attachments
+
+```ruby
+photo = client.uploads.upload_photo_from_file(path: "./image.png")
+
+message = MaxBotApi::Builders::MessageBuilder.new
+  .set_chat(12345)
+  .add_photo(photo)
+
+client.messages.send(message)
+```
+
+## Error handling
+
+```ruby
+begin
+  client.bots.get_bot
+rescue MaxBotApi::ApiError => e
+  puts "API error: #{e.message}"
+rescue MaxBotApi::TimeoutError => e
+  puts "Timeout: #{e.message}"
+end
+```
+
+## More docs
+
+- `docs/01-your-first-bot.md`
+- `docs/02-listen-and-respond.md`
+- `docs/03-attachments.md`
+- `docs/04-keyboard.md`
+- `docs/05-uploads.md`
+- `docs/06-subscriptions.md`
+
+## Examples
+
+See `examples/` for ready-to-run scripts.

data/docs/01-your-first-bot.md

@@ -0,0 +1,44 @@
+# 1. Your First Bot
+
+This guide shows how to create a basic bot using the Ruby client.
+
+## Get a token
+
+Open a dialog with [MasterBot](https://max.ru/masterbot) and create a bot. You will receive a token.
+
+## Install the gem
+
+```bash
+gem install max_bot_api
+```
+
+## Minimal bot
+
+```ruby
+require "max_bot_api"
+
+client = MaxBotApi::Client.new(token: ENV.fetch("TOKEN"))
+
+me = client.bots.get_bot
+puts "Hello, #{me[:name]}"
+```
+
+## Send a message
+
+```ruby
+message = MaxBotApi::Builders::MessageBuilder.new
+  .set_chat(12345)
+  .set_text("Hello from Ruby")
+
+client.messages.send(message)
+```
+
+## Configuration
+
+```ruby
+client = MaxBotApi::Client.new(
+  token: ENV.fetch("TOKEN"),
+  base_url: "https://botapi.max.ru/",
+  version: "1.2.5"
+)
+```

data/docs/02-listen-and-respond.md

@@ -0,0 +1,64 @@
+# 2. Listen and Respond
+
+You can receive updates via long polling or webhooks.
+
+## Long polling
+
+```ruby
+client = MaxBotApi::Client.new(token: ENV.fetch("TOKEN"))
+
+client.each_update do |update|
+  case update[:update_type]
+  when "message_created"
+    text = update.dig(:message, :body, :text)
+    puts "New message: #{text}"
+  when "bot_started"
+    puts "Bot started"
+  end
+end
+```
+
+### Advanced polling options
+
+```ruby
+client.each_update(
+  limit: 50,
+  timeout: 30,
+  pause: 1,
+  types: ["message_created", "message_callback"]
+) do |update|
+  # ...
+end
+```
+
+## Webhook handling
+
+```ruby
+post "/webhook" do
+  update = client.parse_webhook(request.body.read)
+
+  case update[:update_type]
+  when "message_created"
+    # ...
+  end
+
+  status 200
+end
+```
+
+## Updates model
+
+Updates are returned as hashes. The `update_type` field maps to the official types:
+
+- `message_created`
+- `message_edited`
+- `message_removed`
+- `message_callback`
+- `bot_added`
+- `bot_removed`
+- `bot_started`
+- `user_added`
+- `user_removed`
+- `chat_title_changed`
+
+If you enable `debug: true` in `parse_webhook` or `each_update`, the update includes `:debug_raw`.

data/docs/03-attachments.md

@@ -0,0 +1,49 @@
+# 3. Attachments
+
+Use `uploads` to upload files and then attach them to a message.
+
+## Upload from file
+
+```ruby
+photo = client.uploads.upload_photo_from_file(path: "./image.png")
+
+message = MaxBotApi::Builders::MessageBuilder.new
+  .set_chat(12345)
+  .add_photo(photo)
+
+client.messages.send(message)
+```
+
+## Upload from URL
+
+```ruby
+audio = client.uploads.upload_media_from_url(type: :audio, url: "https://example.com/audio.mp3")
+
+message = MaxBotApi::Builders::MessageBuilder.new
+  .set_chat(12345)
+  .add_audio(audio)
+
+client.messages.send(message)
+```
+
+## Other attachment helpers
+
+- `add_video(uploaded_info)`
+- `add_file(uploaded_info)`
+- `add_location(lat, lon)`
+- `add_contact(name:, contact_id:, vcf_info:, vcf_phone:)`
+- `add_sticker(code)`
+
+## Photo tokens
+
+When you upload photos, you receive a token payload. Pass it to `add_photo`:
+
+```ruby
+photo_tokens = client.uploads.upload_photo_from_file(path: "./image.png")
+
+message = MaxBotApi::Builders::MessageBuilder.new
+  .set_chat(12345)
+  .add_photo(photo_tokens)
+
+client.messages.send(message)
+```

data/docs/04-keyboard.md

@@ -0,0 +1,36 @@
+# 4. Keyboard
+
+The keyboard builder mirrors the Go client.
+
+```ruby
+keyboard = client.messages.new_keyboard_builder
+keyboard
+  .add_row
+  .add_geolocation("Share location", true)
+  .add_contact("Share contact")
+
+keyboard
+  .add_row
+  .add_link("Open MAX", "positive", "https://max.ru")
+  .add_callback("Audio", "negative", "audio")
+  .add_callback("Video", "negative", "video")
+
+keyboard
+  .add_row
+  .add_callback("Picture", "positive", "picture")
+
+message = MaxBotApi::Builders::MessageBuilder.new
+  .set_chat(12345)
+  .add_keyboard(keyboard)
+  .set_text("Choose an action")
+
+client.messages.send(message)
+```
+
+## Button types
+
+- `add_callback(text, intent, payload)`
+- `add_link(text, intent, url)`
+- `add_contact(text)`
+- `add_geolocation(text, quick)`
+- `add_open_app(text, app, payload, contact_id)`

data/docs/05-uploads.md

@@ -0,0 +1,50 @@
+# 5. Uploads
+
+Uploads use a two-step flow:
+
+1. `POST /uploads?type=...` to get a temporary upload URL.
+2. `POST` multipart data to that URL with field `data`.
+
+This is handled automatically by `MaxBotApi::Resources::Uploads`.
+
+## Media upload types
+
+- `:photo` (image)
+- `:video`
+- `:audio`
+- `:file`
+
+## From disk
+
+```ruby
+video = client.uploads.upload_media_from_file(type: :video, filename: "./video.mp4")
+message = MaxBotApi::Builders::MessageBuilder.new
+  .set_chat(12345)
+  .add_video(video)
+
+client.messages.send(message)
+```
+
+## From URL
+
+```ruby
+doc = client.uploads.upload_media_from_url(type: :file, url: "https://example.com/doc.pdf")
+message = MaxBotApi::Builders::MessageBuilder.new
+  .set_chat(12345)
+  .add_file(doc)
+
+client.messages.send(message)
+```
+
+## From IO
+
+```ruby
+File.open("./audio.mp3", "rb") do |io|
+  audio = client.uploads.upload_media_from_reader(type: :audio, io: io)
+  message = MaxBotApi::Builders::MessageBuilder.new
+    .set_chat(12345)
+    .add_audio(audio)
+
+  client.messages.send(message)
+end
+```

data/docs/06-subscriptions.md

@@ -0,0 +1,28 @@
+# 6. Subscriptions (Webhooks)
+
+Use subscriptions to receive webhook updates.
+
+## Subscribe
+
+```ruby
+client = MaxBotApi::Client.new(token: ENV.fetch("TOKEN"))
+
+client.subscriptions.subscribe(
+  url: "https://example.com/webhook",
+  update_types: ["message_created", "message_callback"],
+  secret: "my-secret"
+)
+```
+
+## Unsubscribe
+
+```ruby
+client.subscriptions.unsubscribe(url: "https://example.com/webhook")
+```
+
+## List subscriptions
+
+```ruby
+subscriptions = client.subscriptions.get_subscriptions
+puts subscriptions[:subscriptions].inspect
+```

data/examples/attachments.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'max_bot_api'
+
+client = MaxBotApi::Client.new(token: ENV.fetch('TOKEN'))
+chat_id = ENV.fetch('CHAT_ID').to_i
+
+photo = client.uploads.upload_photo_from_file(path: './image.png')
+
+message = MaxBotApi::Builders::MessageBuilder.new
+                                             .set_chat(chat_id)
+                                             .add_photo(photo)
+                                             .set_text('Photo attached')
+
+client.messages.send(message)

data/examples/basic_send.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'max_bot_api'
+
+client = MaxBotApi::Client.new(token: ENV.fetch('TOKEN'))
+
+message = MaxBotApi::Builders::MessageBuilder.new
+                                             .set_chat(ENV.fetch('CHAT_ID').to_i)
+                                             .set_text('Hello from Ruby')
+
+client.messages.send(message)
+puts 'Sent'

data/examples/keyboard.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'max_bot_api'
+
+client = MaxBotApi::Client.new(token: ENV.fetch('TOKEN'))
+chat_id = ENV.fetch('CHAT_ID').to_i
+
+keyboard = client.messages.new_keyboard_builder
+keyboard
+  .add_row
+  .add_geolocation('Share location', true)
+  .add_contact('Share contact')
+
+keyboard
+  .add_row
+  .add_link('Open MAX', 'positive', 'https://max.ru')
+  .add_callback('Audio', 'negative', 'audio')
+
+message = MaxBotApi::Builders::MessageBuilder.new
+                                             .set_chat(chat_id)
+                                             .add_keyboard(keyboard)
+                                             .set_text('Choose an action')
+
+client.messages.send(message)

data/examples/long_poll.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'max_bot_api'
+
+client = MaxBotApi::Client.new(token: ENV.fetch('TOKEN'))
+
+client.each_update do |update|
+  next unless update[:update_type] == 'message_created'
+
+  chat_id = update.dig(:message, :recipient, :chat_id)
+  text = update.dig(:message, :body, :text)
+
+  message = MaxBotApi::Builders::MessageBuilder.new
+                                               .set_chat(chat_id)
+                                               .set_text("Echo: #{text}")
+
+  client.messages.send(message)
+end

data/examples/subscriptions.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'max_bot_api'
+
+client = MaxBotApi::Client.new(token: ENV.fetch('TOKEN'))
+
+url = ENV.fetch('WEBHOOK_URL')
+
+client.subscriptions.subscribe(
+  url: url,
+  update_types: %w[message_created message_callback],
+  secret: 'my-secret'
+)
+
+puts "Subscribed to #{url}"

data/examples/uploads.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'max_bot_api'
+
+client = MaxBotApi::Client.new(token: ENV.fetch('TOKEN'))
+chat_id = ENV.fetch('CHAT_ID').to_i
+
+audio = client.uploads.upload_media_from_file(type: :audio, filename: './audio.mp3')
+
+message = MaxBotApi::Builders::MessageBuilder.new
+                                             .set_chat(chat_id)
+                                             .add_audio(audio)
+
+client.messages.send(message)

data/examples/webhook_rack.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'max_bot_api'
+require 'rack'
+
+client = MaxBotApi::Client.new(token: ENV.fetch('TOKEN'))
+
+app = lambda do |env|
+  req = Rack::Request.new(env)
+  if req.post? && req.path == '/webhook'
+    update = client.parse_webhook(req.body.read)
+
+    if update[:update_type] == 'message_created'
+      chat_id = update.dig(:message, :recipient, :chat_id)
+      message = MaxBotApi::Builders::MessageBuilder.new
+                                                   .set_chat(chat_id)
+                                                   .set_text('Hello from webhook')
+
+      client.messages.send(message)
+    end
+
+    [200, { 'Content-Type' => 'text/plain' }, ['ok']]
+  else
+    [404, { 'Content-Type' => 'text/plain' }, ['not found']]
+  end
+end
+
+Rack::Handler::WEBrick.run(app, Port: 10_888)

data/lib/max_bot_api/builders/keyboard_builder.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module MaxBotApi
+  module Builders
+    # Builder for inline keyboards.
+    class KeyboardBuilder
+      def initialize
+        @rows = []
+      end
+
+      # Add a new row to the keyboard.
+      def add_row
+        row = KeyboardRowBuilder.new
+        @rows << row
+        row
+      end
+
+      # Build keyboard payload.
+      def build
+        { buttons: @rows.map(&:build) }
+      end
+    end
+
+    # Builder for a single keyboard row.
+    class KeyboardRowBuilder
+      def initialize
+        @cols = []
+      end
+
+      # Add a prebuilt button hash.
+      def add_button(button)
+        @cols << button
+        self
+      end
+
+      # Add a link button.
+      def add_link(text, _intent, url)
+        button = {
+          type: 'link',
+          text: text,
+          url: url
+        }
+        add_button(button)
+      end
+
+      # Add a callback button.
+      def add_callback(text, intent, payload)
+        button = {
+          type: 'callback',
+          text: text,
+          payload: payload,
+          intent: intent
+        }
+        add_button(button)
+      end
+
+      # Add a contact request button.
+      def add_contact(text)
+        button = {
+          type: 'request_contact',
+          text: text
+        }
+        add_button(button)
+      end
+
+      # Add a geolocation request button.
+      def add_geolocation(text, quick)
+        button = {
+          type: 'request_geo_location',
+          text: text,
+          quick: quick
+        }
+        add_button(button)
+      end
+
+      # Add an open app button.
+      def add_open_app(text, app, payload, contact_id)
+        button = {
+          type: 'open_app',
+          text: text,
+          web_app: app,
+          payload: payload,
+          contact_id: contact_id
+        }
+        add_button(button)
+      end
+
+      # Build row payload.
+      def build
+        @cols
+      end
+    end
+  end
+end