max_bot_api 0.1.0

data/lib/max_bot_api/resources/messages.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require 'cgi'
+
+module MaxBotApi
+  module Resources
+    # Messages API methods.
+    class Messages
+      def initialize(client)
+        @client = client
+      end
+
+      # List messages with filters.
+      def get_messages(chat_id: nil, message_ids: nil, from: nil, to: nil, count: nil)
+        query = {}
+        query['chat_id'] = chat_id if chat_id && chat_id.to_i != 0
+        Array(message_ids).each do |mid|
+          query['message_ids'] ||= []
+          query['message_ids'] << mid
+        end
+        query['from'] = from if from && from.to_i != 0
+        query['to'] = to if to && to.to_i != 0
+        query['count'] = count if count && count.to_i > 0
+
+        @client.request(:get, 'messages', query: normalize_array_query(query))
+      end
+
+      # Fetch a single message by ID.
+      # @param message_id [String]
+      def get_message(message_id:)
+        path = "messages/#{CGI.escape(message_id.to_s)}"
+        @client.request(:get, path)
+      end
+
+      # Edit a message by ID.
+      # @param message_id [String]
+      # @param message [MaxBotApi::Builders::MessageBuilder, Hash]
+      def edit_message(message_id:, message:)
+        body = message_payload(message)
+        result = @client.request(:put, 'messages', query: { 'message_id' => message_id }, body: body)
+        return true if result.is_a?(Hash) && result[:success]
+
+        raise Error, (result[:message] || 'message update failed')
+      end
+
+      # Delete a message by ID.
+      # @param message_id [String]
+      def delete_message(message_id:)
+        @client.request(:delete, 'messages', query: { 'message_id' => message_id })
+      end
+
+      # Answer a callback button press.
+      # @param callback_id [String]
+      # @param answer [Hash]
+      def answer_on_callback(callback_id:, answer:)
+        @client.request(:post, 'answers', query: { 'callback_id' => callback_id }, body: answer)
+      end
+
+      # Build a keyboard using the helper.
+      def new_keyboard_builder
+        Builders::KeyboardBuilder.new
+      end
+
+      # Send a message builder without returning the created message.
+      # @param message [MaxBotApi::Builders::MessageBuilder, Hash]
+      def send(message)
+        send_message(message, with_result: false)
+      end
+
+      # Send a message builder and return the created message hash.
+      # @param message [MaxBotApi::Builders::MessageBuilder, Hash]
+      def send_with_result(message)
+        send_message(message, with_result: true)
+      end
+
+      # Check if a message can be sent to the provided phone numbers.
+      # @param message [MaxBotApi::Builders::MessageBuilder, Hash]
+      def check(message)
+        message = ensure_builder(message)
+        query = {}
+        query['access_token'] = message.bot_token if message.reset?
+        query['phone_numbers'] = Array(message.phone_numbers).join(',') if message.phone_numbers
+
+        result = @client.request(:get, 'notify/exists', query: query, reset: message.reset?)
+        numbers = Array(result[:existing_phone_numbers])
+        [!numbers.empty?, result]
+      end
+
+      # List phone numbers that exist in MAX.
+      # @param message [MaxBotApi::Builders::MessageBuilder, Hash]
+      def list_exist(message)
+        message = ensure_builder(message)
+        query = {}
+        query['access_token'] = message.bot_token if message.reset?
+        query['phone_numbers'] = Array(message.phone_numbers).join(',') if message.phone_numbers
+
+        result = @client.request(:get, 'notify/exists', query: query, reset: message.reset?)
+        numbers = Array(result[:existing_phone_numbers])
+        [numbers.empty? ? nil : numbers, result]
+      end
+
+      private
+
+      def send_message(message, with_result:)
+        message = ensure_builder(message)
+        query = {}
+        query['chat_id'] = message.chat_id if message.chat_id && message.chat_id.to_i != 0
+        query['user_id'] = message.user_id if message.user_id && message.user_id.to_i != 0
+
+        response = @client.request(:post, 'messages', query: query, body: message_payload(message),
+                                                      reset: message.reset?)
+        return response[:message] if with_result && response.is_a?(Hash)
+
+        nil
+      end
+
+      def message_payload(message)
+        message.is_a?(Builders::MessageBuilder) ? message.to_h : message
+      end
+
+      def ensure_builder(message)
+        return message if message.is_a?(Builders::MessageBuilder)
+
+        Builders::MessageBuilder.from_hash(message)
+      end
+
+      def normalize_array_query(query)
+        query.each_with_object({}) do |(key, value), acc|
+          acc[key] = if value.is_a?(Array)
+                       value
+                     else
+                       value
+                     end
+        end
+      end
+    end
+  end
+end

data/lib/max_bot_api/resources/subscriptions.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module MaxBotApi
+  module Resources
+    # Webhook subscription methods.
+    class Subscriptions
+      def initialize(client)
+        @client = client
+      end
+
+      # List active subscriptions.
+      def get_subscriptions
+        @client.request(:get, 'subscriptions')
+      end
+
+      # Create a webhook subscription.
+      # @param url [String]
+      # @param update_types [Array<String>]
+      # @param secret [String, nil]
+      def subscribe(url:, update_types: [], secret: nil)
+        body = {
+          url: url,
+          update_types: update_types,
+          secret: secret,
+          version: @client.version
+        }.compact
+
+        @client.request(:post, 'subscriptions', body: body)
+      end
+
+      # Remove a webhook subscription.
+      # @param url [String]
+      def unsubscribe(url:)
+        @client.request(:delete, 'subscriptions', query: { 'url' => url })
+      end
+    end
+  end
+end

data/lib/max_bot_api/resources/uploads.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'stringio'
+
+module MaxBotApi
+  module Resources
+    # Upload helpers for media and photos.
+    class Uploads
+      UPLOAD_TYPES = {
+        photo: 'image',
+        video: 'video',
+        audio: 'audio',
+        file: 'file'
+      }.freeze
+
+      def initialize(client)
+        @client = client
+      end
+
+      # Upload media from a local file.
+      # @param type [Symbol, String]
+      # @param filename [String]
+      def upload_media_from_file(type:, filename:)
+        File.open(filename, 'rb') do |fh|
+          upload_media_from_reader_with_name(type: type, io: fh, name: File.basename(filename))
+        end
+      end
+
+      # Upload media from a remote URL.
+      # @param type [Symbol, String]
+      # @param url [String]
+      def upload_media_from_url(type:, url:)
+        response = Faraday.get(url.to_s)
+        name = attachment_name(response.headers)
+        upload_media_from_reader_with_name(type: type, io: StringIO.new(response.body), name: name)
+      end
+
+      # Upload media from an IO object.
+      # @param type [Symbol, String]
+      # @param io [#read]
+      def upload_media_from_reader(type:, io:)
+        upload_media_from_reader_with_name(type: type, io: io, name: nil)
+      end
+
+      # Upload media from IO with explicit name.
+      # @param type [Symbol, String]
+      # @param io [#read]
+      # @param name [String, nil]
+      def upload_media_from_reader_with_name(type:, io:, name: nil)
+        upload_media_from_reader_internal(type: type, io: io, name: name)
+      end
+
+      # Upload a photo from a local file.
+      # @param path [String]
+      def upload_photo_from_file(path:)
+        upload_media_from_file(type: :photo, filename: path)
+      end
+
+      # Upload a photo from base64 content.
+      # @param code [String]
+      def upload_photo_from_base64_string(code:)
+        decoded = Base64.decode64(code)
+        upload_media_from_reader_with_name(type: :photo, io: StringIO.new(decoded), name: nil)
+      end
+
+      # Upload a photo from a remote URL.
+      # @param url [String]
+      def upload_photo_from_url(url:)
+        upload_media_from_url(type: :photo, url: url)
+      end
+
+      # Upload a photo from an IO object.
+      # @param io [#read]
+      def upload_photo_from_reader(io:)
+        upload_media_from_reader(type: :photo, io: io)
+      end
+
+      # Upload a photo from IO with explicit name.
+      # @param io [#read]
+      # @param name [String]
+      def upload_photo_from_reader_with_name(io:, name:)
+        upload_media_from_reader_with_name(type: :photo, io: io, name: name)
+      end
+
+      private
+
+      def upload_media_from_reader_internal(type:, io:, name: nil)
+        upload_type = UPLOAD_TYPES.fetch(type.to_sym) { type.to_s }
+        endpoint = @client.request(:post, 'uploads', query: { 'type' => upload_type })
+
+        file_name = name.to_s.empty? ? 'file' : name.to_s
+        file_part = Faraday::Multipart::FilePart.new(io, nil, file_name)
+
+        response = Faraday.post(endpoint[:url]) do |req|
+          req.body = { 'data' => file_part }
+        end
+
+        raise Error, "upload failed: #{response.status}" unless response.status == 200
+
+        JSON.parse(response.body, symbolize_names: true)
+      rescue Faraday::Error => e
+        raise NetworkError.new(op: 'POST uploads', original_error: e)
+      end
+
+      def attachment_name(headers)
+        disposition = headers['content-disposition'].to_s
+        return '' if disposition.empty?
+
+        match = disposition.match(/filename="?([^";]+)"?/)
+        match ? match[1] : ''
+      end
+    end
+  end
+end

data/lib/max_bot_api/updates/parser.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module MaxBotApi
+  module Updates
+    # Update parsing helpers.
+    class Parser
+      # Parse a single update JSON string or hash.
+      # @param data [String, Hash]
+      # @param debug [Boolean]
+      # @return [Hash]
+      def self.parse_update(data, debug: false)
+        raw = data.is_a?(String) ? data : JSON.generate(data)
+        update = data.is_a?(Hash) ? deep_symbolize_keys(data) : JSON.parse(raw, symbolize_names: true)
+
+        update[:debug_raw] = raw if debug
+        normalize_attachments!(update)
+        update
+      end
+
+      # Parse a list of updates.
+      # @param data [String, Hash]
+      # @param debug [Boolean]
+      # @return [Hash]
+      def self.parse_update_list(data, debug: false)
+        list = data.is_a?(Hash) ? data : JSON.parse(data.to_s, symbolize_names: true)
+        updates = Array(list[:updates])
+        list[:updates] = updates.map { |u| parse_update(u, debug: debug) }
+        list
+      end
+
+      # Normalize attachment payloads to symbolized hashes.
+      def self.normalize_attachments!(update)
+        message = update.dig(:message)
+        body = message && message[:body]
+        if body && body[:attachments].is_a?(Array)
+          body[:attachments] = body[:attachments].map { |att| deep_symbolize_keys(att) }
+        end
+
+        linked_body = update.dig(:message, :link, :message, :attachments)
+        return unless linked_body.is_a?(Array)
+
+        update[:message][:link][:message][:attachments] = linked_body.map { |att| deep_symbolize_keys(att) }
+      end
+
+      # Deep symbolize hash keys.
+      def self.deep_symbolize_keys(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(k, v), acc|
+            acc[k.to_sym] = deep_symbolize_keys(v)
+          end
+        when Array
+          value.map { |item| deep_symbolize_keys(item) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/max_bot_api/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module MaxBotApi
+  # Gem version.
+  VERSION = '0.1.0'
+end

data/lib/max_bot_api.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/multipart'
+require 'json'
+
+require_relative 'max_bot_api/version'
+require_relative 'max_bot_api/errors'
+require_relative 'max_bot_api/client'
+
+require_relative 'max_bot_api/builders/message_builder'
+require_relative 'max_bot_api/builders/keyboard_builder'
+
+require_relative 'max_bot_api/updates/parser'
+
+require_relative 'max_bot_api/resources/bots'
+require_relative 'max_bot_api/resources/chats'
+require_relative 'max_bot_api/resources/messages'
+require_relative 'max_bot_api/resources/subscriptions'
+require_relative 'max_bot_api/resources/uploads'
+require_relative 'max_bot_api/resources/debugs'

metadata

@@ -0,0 +1,140 @@
+--- !ruby/object:Gem::Specification
+name: max_bot_api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ChatGPT Codex
+- Dmitry Merkushin
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: faraday-multipart
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+description: Ruby gem that mirrors the MAX Bot API Go client.
+email:
+- merkushin@hey.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- 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/attachments.rb
+- examples/basic_send.rb
+- examples/keyboard.rb
+- examples/long_poll.rb
+- examples/subscriptions.rb
+- examples/uploads.rb
+- examples/webhook_rack.rb
+- lib/max_bot_api.rb
+- lib/max_bot_api/builders/keyboard_builder.rb
+- lib/max_bot_api/builders/message_builder.rb
+- lib/max_bot_api/client.rb
+- lib/max_bot_api/errors.rb
+- lib/max_bot_api/resources/bots.rb
+- lib/max_bot_api/resources/chats.rb
+- lib/max_bot_api/resources/debugs.rb
+- lib/max_bot_api/resources/messages.rb
+- lib/max_bot_api/resources/subscriptions.rb
+- lib/max_bot_api/resources/uploads.rb
+- lib/max_bot_api/updates/parser.rb
+- lib/max_bot_api/version.rb
+homepage: https://github.com/creogen/max_bot_api
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/creogen/max_bot_api
+  source_code_uri: https://github.com/creogen/max_bot_api/tree/main
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Ruby client for MAX Bot API
+test_files: []