telegram_client.rb

class TelegramClient < AppClient
  def self.bot_token
    ".............................................."
  end

  def self.base_url
    "https://api.telegram.org/bot#{bot_token}"
  end

  helper_class :loggable,
               :Updates,
               :Basic,
               :Messaging,
               :Files,
               :Chat,
               :Stickers,
               :Inline,
               :Payments

  class Updates
    # Retrieves incoming updates for the bot.
    # @param offset [Integer] Identifier of the first update to be returned. Optional.
    # @param limit [Integer] Limits the number of updates to be retrieved. Default is 100. Optional.
    # @param timeout [Integer] Timeout in seconds for long polling. Optional.
    # @param allowed_updates [Array<String>] List of update types to receive. Optional.
    def self.get_updates(
      offset: nil,
      limit: nil,
      timeout: nil,
      allowed_updates: nil
    )
      payload = {
        offset: offset,
        limit: limit,
        timeout: timeout,
        allowed_updates: allowed_updates
      }.compact

      post("#{base_url}/getUpdates", payload)
    end

    # Sets a webhook to receive incoming updates via an HTTPS POST.
    # @param url [String] HTTPS URL to send updates to. Required.
    # @param certificate [File] Public key certificate for webhook. Optional.
    # @param ip_address [String] Fixed IP address for webhook. Optional.
    # @param max_connections [Integer] Maximum allowed simultaneous connections. Optional.
    # @param allowed_updates [Array<String>] List of update types to receive. Optional.
    def self.set_webhook(
      url:,
      certificate: nil,
      ip_address: nil,
      max_connections: nil,
      allowed_updates: nil
    )
      payload = {
        url: url,
        certificate: certificate,
        ip_address: ip_address,
        max_connections: max_connections,
        allowed_updates: allowed_updates
      }.compact

      post("#{base_url}/setWebhook", payload)
    end

    # Removes the webhook integration.
    # @param drop_pending_updates [Boolean] Whether to drop all pending updates. Optional.
    def self.delete_webhook(drop_pending_updates: nil)
      payload = { drop_pending_updates: drop_pending_updates }.compact

      post("#{base_url}/deleteWebhook", payload)
    end

    # Provides current webhook status.
    def self.get_webhook_info
      self.get("#{base_url}/getWebhookInfo")
    end
  end

  class Basic
    # Retrieves basic information about the bot.
    def self.get_me
      self.get("#{base_url}/getMe")
    end

    # Logs out from the cloud Bot API server.
    def self.log_out
      post("#{base_url}/logOut", {})
    end

    # Closes the bot instance before moving it from one local server to another.
    def self.close
      post("#{base_url}/close", {})
    end
  end

  class Messaging
    # Sends a text message to a chat.
    #
    # @param chat_id [Integer, String] Unique identifier for the target chat or username of the target channel.
    # @param text [String] The message text to be sent.
    # @param parse_mode [String] Parsing style for text (Markdown, HTML, etc.). Optional.
    # @param disable_web_page_preview [Boolean] Disable link previews in the message. Optional.
    # @param disable_notification [Boolean] Send the message silently. Optional.
    # @param reply_to_message_id [Integer] ID of the message to reply to. Optional.
    # @param reply_markup [Hash] Additional interface options (keyboards, etc.). Optional.
    def self.send_message(
      chat_id:,
      text:,
      parse_mode: nil,
      disable_web_page_preview: nil,
      disable_notification: nil,
      reply_to_message_id: nil,
      reply_markup: nil
    )
      payload = {
        chat_id: chat_id,
        text: text,
        parse_mode: parse_mode,
        disable_web_page_preview: disable_web_page_preview,
        disable_notification: disable_notification,
        reply_to_message_id: reply_to_message_id,
        reply_markup: reply_markup
      }.compact

      post("#{base_url}/sendMessage", payload)
    end

    # Forwards a message from one chat to another.
    #
    # @param chat_id [Integer, String] Unique identifier for the target chat or username of the target channel.
    # @param from_chat_id [Integer, String] Unique identifier for the chat where the message originates.
    # @param message_id [Integer] The message ID to forward.
    # @param disable_notification [Boolean] Send the forwarded message silently. Optional.
    def self.forward_message(
      chat_id:,
      from_chat_id:,
      message_id:,
      disable_notification: nil
    )
      payload = {
        chat_id: chat_id,
        from_chat_id: from_chat_id,
        message_id: message_id,
        disable_notification: disable_notification
      }.compact

      post("#{base_url}/forwardMessage", payload)
    end

    # Copies a message from one chat to another without linking to the original message.
    #
    # @param chat_id [Integer, String] Unique identifier for the target chat or username of the target channel.
    # @param from_chat_id [Integer, String] Unique identifier for the chat where the message originates.
    # @param message_id [Integer] The message ID to copy.
    # @param caption [String] New caption for the copied message. Optional.
    # @param parse_mode [String] Parsing style for caption text (Markdown, HTML, etc.). Optional.
    # @param caption_entities [Array<Hash>] Special entities for the caption. Optional.
    # @param disable_notification [Boolean] Send the copied message silently. Optional.
    # @param reply_to_message_id [Integer] ID of the message to reply to. Optional.
    # @param reply_markup [Hash] Additional interface options (keyboards, etc.). Optional.
    def self.copy_message(
      chat_id:,
      from_chat_id:,
      message_id:,
      caption: nil,
      parse_mode: nil,
      caption_entities: nil,
      disable_notification: nil,
      reply_to_message_id: nil,
      reply_markup: nil
    )
      payload = {
        chat_id: chat_id,
        from_chat_id: from_chat_id,
        message_id: message_id,
        caption: caption,
        parse_mode: parse_mode,
        caption_entities: caption_entities,
        disable_notification: disable_notification,
        reply_to_message_id: reply_to_message_id,
        reply_markup: reply_markup
      }.compact

      post("#{base_url}/copyMessage", payload)
    end

    # Sends a photo to a chat.
    #
    # @param chat_id [Integer, String] Unique identifier for the target chat or username of the target channel.
    # @param photo [String, File] Photo to send (file path, URL, or file ID).
    # @param caption [String] Caption for the photo. Optional.
    # @param parse_mode [String] Parsing style for caption text (Markdown, HTML, etc.). Optional.
    # @param caption_entities [Array<Hash>] Special entities for the caption. Optional.
    # @param disable_notification [Boolean] Send the photo silently. Optional.
    # @param reply_to_message_id [Integer] ID of the message to reply to. Optional.
    # @param reply_markup [Hash] Additional interface options (keyboards, etc.). Optional.
    def self.send_photo(
      chat_id:,
      photo:,
      caption: nil,
      parse_mode: nil,
      caption_entities: nil,
      disable_notification: nil,
      reply_to_message_id: nil,
      reply_markup: nil
    )
      payload = {
        chat_id: chat_id,
        photo: photo,
        caption: caption,
        parse_mode: parse_mode,
        caption_entities: caption_entities,
        disable_notification: disable_notification,
        reply_to_message_id: reply_to_message_id,
        reply_markup: reply_markup
      }.compact

      post("#{base_url}/sendPhoto", payload)
    end

    # Sends a document to a chat.
    #
    # @param chat_id [Integer, String] Unique identifier for the target chat or username of the target channel.
    # @param document [String, File] Document to send (file path, URL, or file ID).
    # @param caption [String] Caption for the document. Optional.
    # @param parse_mode [String] Parsing style for caption text (Markdown, HTML, etc.). Optional.
    # @param caption_entities [Array<Hash>] Special entities for the caption. Optional.
    # @param disable_notification [Boolean] Send the document silently. Optional.
    # @param reply_to_message_id [Integer] ID of the message to reply to. Optional.
    # @param reply_markup [Hash] Additional interface options (keyboards, etc.). Optional.
    def self.send_document(
      chat_id:,
      document:,
      caption: nil,
      parse_mode: nil,
      caption_entities: nil,
      disable_notification: nil,
      reply_to_message_id: nil,
      reply_markup: nil
    )
      payload = {
        chat_id: chat_id,
        document: document,
        caption: caption,
        parse_mode: parse_mode,
        caption_entities: caption_entities,
        disable_notification: disable_notification,
        reply_to_message_id: reply_to_message_id,
        reply_markup: reply_markup
      }.compact

      post("#{base_url}/sendDocument", payload)
    end
  end

  class Files
    # Retrieves a user's profile photos.
    #
    # @param user_id [Integer] Unique identifier of the target user.
    # @param offset [Integer] Sequential number of the first photo to be returned. Optional.
    # @param limit [Integer] Limits the number of photos to be retrieved (default is 100). Optional.
    # @return [Hash] User profile photos metadata.
    def self.get_user_profile_photos(user_id:, offset: nil, limit: nil)
      payload = { user_id: user_id, offset: offset, limit: limit }.compact

      post("#{base_url}/getUserProfilePhotos", payload)
    end

    # Retrieves basic information about a file and prepares it for downloading.
    #
    # @param file_id [String] File identifier to get info about.
    # @return [Hash] File information, including the file path.
    def self.get_file(file_id:)
      payload = { file_id: file_id }

      post("#{base_url}/getFile", payload)
    end

    # Downloads a file from Telegram servers using its file path.
    #
    # @param file_path [String] Path of the file on Telegram's servers.
    # @return [File] The downloaded file content.
    def self.download_file(file_path:)
      url = "https://api.telegram.org/file/bot#{bot_token}/#{file_path}"
      get(url)
    end
  end

  class Chat
    # Retrieves up-to-date information about a chat.
    #
    # @param chat_id [Integer, String] Unique identifier for the target chat or username of the target channel.
    # @return [Hash] Chat information, including type, title, and members count.
    def self.get_chat(chat_id:)
      payload = { chat_id: chat_id }
      post("#{base_url}/getChat", payload)
    end

    # Retrieves a list of administrators in a chat.
    #
    # @param chat_id [Integer, String] Unique identifier for the target chat or username of the target channel.
    # @return [Array<Hash>] List of chat administrators and their roles.
    def self.get_chat_administrators(chat_id:)
      payload = { chat_id: chat_id }
      post("#{base_url}/getChatAdministrators", payload)
    end

    # Retrieves the number of members in a chat.
    #
    # @param chat_id [Integer, String] Unique identifier for the target chat or username of the target channel.
    # @return [Integer] Number of members in the chat.
    def self.get_chat_member_count(chat_id:)
      payload = { chat_id: chat_id }
      post("#{base_url}/getChatMemberCount", payload)
    end

    # Retrieves information about a member of a chat.
    #
    # @param chat_id [Integer, String] Unique identifier for the target chat or username of the target channel.
    # @param user_id [Integer] Unique identifier of the target user.
    # @return [Hash] Member information, including status and permissions.
    def self.get_chat_member(chat_id:, user_id:)
      payload = { chat_id: chat_id, user_id: user_id }
      post("#{base_url}/getChatMember", payload)
    end

    # Sets a new profile photo for the chat.
    #
    # @param chat_id [Integer, String] Unique identifier for the target chat or username of the target channel.
    # @param photo [File] New chat photo to set.
    # @return [Boolean] True if successful.
    def self.set_chat_photo(chat_id:, photo:)
      payload = { chat_id: chat_id, photo: photo }
      post("#{base_url}/setChatPhoto", payload)
    end

    # Deletes the chat photo.
    #
    # @param chat_id [Integer, String] Unique identifier for the target chat or username of the target channel.
    # @return [Boolean] True if successful.
    def self.delete_chat_photo(chat_id:)
      payload = { chat_id: chat_id }
      post("#{base_url}/deleteChatPhoto", payload)
    end

    # Sets a new title for the chat.
    #
    # @param chat_id [Integer, String] Unique identifier for the target chat or username of the target channel.
    # @param title [String] New title for the chat (1-255 characters).
    # @return [Boolean] True if successful.
    def self.set_chat_title(chat_id:, title:)
      payload = { chat_id: chat_id, title: title }
      post("#{base_url}/setChatTitle", payload)
    end

    # Sets a new description for the chat.
    #
    # @param chat_id [Integer, String] Unique identifier for the target chat or username of the target channel.
    # @param description [String] New chat description (0-255 characters). Optional.
    # @return [Boolean] True if successful.
    def self.set_chat_description(chat_id:, description: nil)
      payload = { chat_id: chat_id, description: description }.compact
      post("#{base_url}/setChatDescription", payload)
    end

    # Pins a message in the chat.
    #
    # @param chat_id [Integer, String] Unique identifier for the target chat or username of the target channel.
    # @param message_id [Integer] Identifier of the message to pin.
    # @param disable_notification [Boolean] If true, no notification will be sent to users. Optional.
    # @return [Boolean] True if successful.
    def self.pin_chat_message(chat_id:, message_id:, disable_notification: nil)
      payload = {
        chat_id: chat_id,
        message_id: message_id,
        disable_notification: disable_notification
      }.compact
      post("#{base_url}/pinChatMessage", payload)
    end

    # Unpins a message in the chat.
    #
    # @param chat_id [Integer, String] Unique identifier for the target chat or username of the target channel.
    # @param message_id [Integer] Identifier of the message to unpin. Optional.
    # @return [Boolean] True if successful.
    def self.unpin_chat_message(chat_id:, message_id: nil)
      payload = { chat_id: chat_id, message_id: message_id }.compact
      post("#{base_url}/unpinChatMessage", payload)
    end

    # Unpins all messages in the chat.
    #
    # @param chat_id [Integer, String] Unique identifier for the target chat or username of the target channel.
    # @return [Boolean] True if successful.
    def self.unpin_all_chat_messages(chat_id:)
      payload = { chat_id: chat_id }
      post("#{base_url}/unpinAllChatMessages", payload)
    end

    # Leaves the chat.
    #
    # @param chat_id [Integer, String] Unique identifier for the target chat or username of the target channel.
    # @return [Boolean] True if successful.
    def self.leave_chat(chat_id:)
      payload = { chat_id: chat_id }
      post("#{base_url}/leaveChat", payload)
    end
  end

  class Stickers
    # Retrieves a sticker set.
    def self.get_sticker_set
      #
    end

    # Uploads a sticker file for later use.
    def self.upload_sticker_file
      #
    end

    # Creates a new sticker set.
    def self.create_new_sticker_set
      #
    end

    # Adds a sticker to a set.
    def self.add_sticker_to_set
      #
    end

    # Moves a sticker in a set to a new position.
    def self.set_sticker_position_in_set
      #
    end

    # Deletes a sticker from a set.
    def self.delete_sticker_from_set
      #
    end
  end

  class Inline
    # Responds to an inline query.
    #
    # @param inline_query_id [String] Unique identifier for the answered query.
    # @param results [Array<Hash>] List of results for the inline query.
    # @param cache_time [Integer] The maximum amount of time the result can be cached in seconds. Optional.
    # @param is_personal [Boolean] If true, results are tailored for the user. Optional.
    # @param next_offset [String] Offset for pagination in next queries. Optional.
    # @param switch_pm_text [String] Text for the "Switch to PM" button. Optional.
    # @param switch_pm_parameter [String] Parameter for the "Switch to PM" button. Optional.
    # @return [Boolean] True if successful.
    def self.answer_inline_query(
      inline_query_id:,
      results:,
      cache_time: nil,
      is_personal: nil,
      next_offset: nil,
      switch_pm_text: nil,
      switch_pm_parameter: nil
    )
      payload = {
        inline_query_id: inline_query_id,
        results: results,
        cache_time: cache_time,
        is_personal: is_personal,
        next_offset: next_offset,
        switch_pm_text: switch_pm_text,
        switch_pm_parameter: switch_pm_parameter
      }.compact

      post("#{base_url}/answerInlineQuery", payload)
    end
  end

  class Payments
    # Sends an invoice.
    def self.send_invoice
      #
    end

    # Responds to shipping queries.
    def self.answer_shipping_query
      #
    end

    # Responds to pre-checkout queries.
    def self.answer_pre_checkout_query
      #
    end
  end
end