onyxcord-webhooks 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 48bbef48168955335002ea4aa8a7f61a6881f7d511290e27461b1f2fec078cbd
+  data.tar.gz: 78511aff20a88484953ca58e471a36572c08c41757853feb83f305c0bf1b87bc
+SHA512:
+  metadata.gz: 3c12912a5a5b79122bf0edfa5c79aa82012461c1bbe8fda4af540564f0823af6e840d00b9ade45c1434b35e5dec93db6524d80b0419a47cd11adf94b56f580ce
+  data.tar.gz: b7181c12ce901f98e925493a9f196c1b2f94676a4b77241780572f4853939ba389b4dfb260c84220c387f9e19290080e8c607ccfff7e47712e1e6f0b45f82664

data/lib/onyxcord/webhooks/builder.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require 'onyxcord/webhooks/embeds'
+require 'onyxcord/message_components'
+
+module OnyxCord::Webhooks
+  # A class that acts as a builder for a webhook message object.
+  class Builder
+    def initialize(content: '', username: nil, avatar_url: nil, tts: false, file: nil, embeds: [], allowed_mentions: nil, poll: nil, flags: 0)
+      @content = content
+      @username = username
+      @avatar_url = avatar_url
+      @tts = tts
+      @file = file
+      @embeds = embeds
+      @allowed_mentions = allowed_mentions
+      @poll = poll
+      @flags = flags
+    end
+
+    # The content of the message. May be 2000 characters long at most.
+    # @return [String] the content of the message.
+    attr_accessor :content
+
+    # The username the webhook will display as. If this is not set, the default username set in the webhook's settings
+    # will be used instead.
+    # @return [String] the username.
+    attr_accessor :username
+
+    # The URL of an image file to be used as an avatar. If this is not set, the default avatar from the webhook's
+    # settings will be used instead.
+    # @return [String] the avatar URL.
+    attr_accessor :avatar_url
+
+    # Whether this message should use TTS or not. By default, it doesn't.
+    # @return [true, false] the TTS status.
+    attr_accessor :tts
+
+    # Message flags to send with this webhook payload.
+    # @return [Integer] the message flags.
+    attr_accessor :flags
+
+    # Enable Discord's Components V2 message flag.
+    # @return [Builder] this builder.
+    def components_v2!
+      @flags = @flags.to_i | OnyxCord::MessageComponents::IS_COMPONENTS_V2
+      self
+    end
+
+    alias has_components! components_v2!
+
+    # @return [true, false] whether Components V2 is enabled on this payload.
+    def components_v2?
+      (@flags.to_i & OnyxCord::MessageComponents::IS_COMPONENTS_V2).positive?
+    end
+
+    # Sets a file to be sent together with the message. Mutually exclusive with embeds; a webhook message can contain
+    # either a file to be sent or an embed.
+    # @param file [File] A file to be sent.
+    def file=(file)
+      raise ArgumentError, 'Embeds and files are mutually exclusive!' unless @embeds.empty?
+
+      @file = file
+    end
+
+    # Adds an embed to this message.
+    # @param embed [Embed] The embed to add.
+    def <<(embed)
+      raise ArgumentError, 'Embeds and files are mutually exclusive!' if @file
+
+      @embeds << embed
+    end
+
+    # Convenience method to add an embed using a block-style builder pattern
+    # @example Add an embed to a message
+    #   builder.add_embed do |embed|
+    #     embed.title = 'Testing'
+    #     embed.image = OnyxCord::Webhooks::EmbedImage.new(url: 'https://i.imgur.com/PcMltU7.jpg')
+    #   end
+    # @param embed [Embed, nil] The embed to start the building process with, or nil if one should be created anew.
+    # @return [Embed] The created embed.
+    def add_embed(embed = nil)
+      embed ||= Embed.new
+      yield(embed)
+      self << embed
+      embed
+    end
+
+    # Convenience method to add a poll using a builder pattern
+    # @example Add a poll to a message
+    #   builder.poll(question: "Best Fruit?", duration: 48) do |poll|
+    #     poll.answer(text: "Apple", emoji: "🍎")
+    #     poll.answer(text: "Orange", emoji: "🍊")
+    #     poll.answer(text: "Pomelo", emoji: "🍈")
+    #   end
+    # @param poll [Poll::Builder, Poll, Hash, nil] The poll to start the building process with, or nil if one should be created anew.
+    # @return [Poll::Builder, Poll] The created poll.
+    def add_poll(poll = nil, **kwargs)
+      poll ||= OnyxCord::Poll::Builder.new(**kwargs)
+      yield(poll) if block_given?
+      @poll = poll
+      poll
+    end
+
+    alias_method :poll, :add_poll
+
+    # @return [File, nil] the file attached to this message.
+    attr_reader :file
+
+    # @return [Array<Embed>] the embeds attached to this message.
+    attr_reader :embeds
+
+    # @return [OnyxCord::AllowedMentions, Hash] Mentions that are allowed to ping in this message.
+    # @see https://discord.com/developers/docs/resources/channel#allowed-mentions-object
+    attr_accessor :allowed_mentions
+
+    # @return [Poll, Poll::Builder, Hash, nil] The poll attached to this message.
+    # @see https://discord.com/developers/docs/resources/poll#poll-create-request-object
+    attr_writer :poll
+
+    # @return [Hash] a hash representation of the created message, for JSON format.
+    def to_json_hash
+      data = {
+        content: @content,
+        username: @username,
+        avatar_url: @avatar_url,
+        tts: @tts,
+        embeds: @embeds.map(&:to_hash),
+        allowed_mentions: @allowed_mentions&.to_hash,
+        poll: @poll&.to_h
+      }
+      data[:flags] = @flags if @flags.to_i.positive?
+      data
+    end
+
+    # @return [Hash] a hash representation of the created message, for multipart format.
+    def to_multipart_hash
+      data = {
+        content: @content,
+        username: @username,
+        avatar_url: @avatar_url,
+        tts: @tts,
+        file: @file,
+        allowed_mentions: @allowed_mentions&.to_hash
+      }
+      data[:flags] = @flags if @flags.to_i.positive?
+      data
+    end
+  end
+end

data/lib/onyxcord/webhooks/client.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require 'rest-client'
+require 'json'
+
+require 'onyxcord/webhooks/builder'
+
+module OnyxCord::Webhooks
+  # A client for a particular webhook added to a Discord channel.
+  class Client
+    # Create a new webhook
+    # @param url [String] The URL to post messages to.
+    # @param id [Integer] The webhook's ID. Will only be used if `url` is not
+    #   set.
+    # @param token [String] The webhook's authorisation token. Will only be used
+    #   if `url` is not set.
+    def initialize(url: nil, id: nil, token: nil)
+      @url = url || generate_url(id, token)
+    end
+
+    # Executes the webhook this client points to with the given data.
+    # @param builder [Builder, nil] The builder to start out with, or nil if one should be created anew.
+    # @param wait [true, false] Whether Discord should wait for the message to be successfully received by clients, or
+    #   whether it should return immediately after sending the message.
+    # @param thread_id [String, Integer, nil] The thread_id of the thread if a thread should be targeted for the webhook execution
+    # @yield [builder] Gives the builder to the block to add additional steps, or to do the entire building process.
+    # @yieldparam builder [Builder] The builder given as a parameter which is used as the initial step to start from.
+    # @example Execute the webhook with an already existing builder
+    #   builder = OnyxCord::Webhooks::Builder.new # ...
+    #   client.execute(builder)
+    # @example Execute the webhook by building a new message
+    #   client.execute do |builder|
+    #     builder.content = 'Testing'
+    #     builder.username = 'onyxcord'
+    #     builder.add_embed do |embed|
+    #       embed.timestamp = Time.now
+    #       embed.title = 'Testing'
+    #       embed.image = OnyxCord::Webhooks::EmbedImage.new(url: 'https://i.imgur.com/PcMltU7.jpg')
+    #     end
+    #   end
+    # @return [RestClient::Response] the response returned by Discord.
+    def execute(builder = nil, wait = false, components = nil, thread_id: nil, flags: nil, has_components: false, components_v2: false)
+      raise TypeError, 'builder needs to be nil or like a OnyxCord::Webhooks::Builder!' unless
+        (builder.respond_to?(:file) && builder.respond_to?(:to_multipart_hash)) || builder.respond_to?(:to_json_hash) || builder.nil?
+
+      builder ||= Builder.new
+      view = View.new
+
+      yield(builder, view) if block_given?
+
+      components ||= view
+
+      if builder.file
+        post_multipart(builder, components, wait, thread_id, flags: flags, has_components: has_components || components_v2)
+      else
+        post_json(builder, components, wait, thread_id, flags: flags, has_components: has_components || components_v2)
+      end
+    end
+
+    # Modify this webhook's properties.
+    # @param name [String, nil] The default name.
+    # @param avatar [String, #read, nil] The new avatar, in base64-encoded JPG format.
+    # @param channel_id [String, Integer, nil] The channel to move the webhook to.
+    # @return [RestClient::Response] the response returned by Discord.
+    def modify(name: nil, avatar: nil, channel_id: nil)
+      RestClient.patch(@url, { name: name, avatar: avatarise(avatar), channel_id: channel_id }.compact.to_json, content_type: :json)
+    end
+
+    # Delete this webhook.
+    # @param reason [String, nil] The reason this webhook was deleted.
+    # @return [RestClient::Response] the response returned by Discord.
+    # @note This is permanent and cannot be undone.
+    def delete(reason: nil)
+      RestClient.delete(@url, 'X-Audit-Log-Reason': reason)
+    end
+
+    # Edit a message from this webhook.
+    # @param message_id [String, Integer] The ID of the message to edit.
+    # @param builder [Builder, nil] The builder to start out with, or nil if one should be created anew.
+    # @param content [String] The message content.
+    # @param embeds [Array<Embed, Hash>]
+    # @param allowed_mentions [Hash]
+    # @param thread_id [String, Integer, nil] The id of the thread in which the message resides
+    # @return [RestClient::Response] the response returned by Discord.
+    # @example Edit message content
+    #   client.edit_message(message_id, content: 'goodbye world!')
+    # @example Edit a message via builder
+    #   client.edit_message(message_id) do |builder|
+    #     builder.add_embed do |e|
+    #       e.description = 'Hello World!'
+    #     end
+    #   end
+    # @note Not all builder options are available when editing.
+    def edit_message(message_id, builder: nil, content: nil, embeds: nil, allowed_mentions: nil, components: nil, flags: nil, thread_id: nil, has_components: false, components_v2: false)
+      builder ||= Builder.new
+
+      yield builder if block_given?
+
+      query = URI.encode_www_form({ thread_id: }.compact)
+      components = View.component_payload(components) unless components.nil?
+      data = builder.to_json_hash
+      builder_flags = data[:flags] if data.is_a?(Hash)
+      flags = View.apply_v2_flag(flags || builder_flags, components, force: has_components || components_v2)
+      data = data.merge({ content: content, embeds: embeds, allowed_mentions: allowed_mentions, components: components, flags: flags }.compact)
+      RestClient.patch(
+        "#{@url}/messages/#{message_id}#{(query.empty? ? '' : "?#{query}")}",
+        data.compact.to_json, content_type: :json
+      )
+    end
+
+    # Delete a message created by this webhook.
+    # @param message_id [String, Integer] The ID of the message to delete.
+    # @return [RestClient::Response] the response returned by Discord.
+    def delete_message(message_id)
+      RestClient.delete("#{@url}/messages/#{message_id}")
+    end
+
+    private
+
+    # Convert an avatar to API ready data.
+    # @param avatar [String, #read] Avatar data.
+    def avatarise(avatar)
+      if avatar.respond_to? :read
+        "data:image/jpg;base64,#{Base64.strict_encode64(avatar.read)}"
+      else
+        avatar
+      end
+    end
+
+    def post_json(builder, components, wait, thread_id, flags: nil, has_components: false)
+      components = View.component_payload(components)
+      data = builder.to_json_hash
+      builder_flags = data[:flags] if data.is_a?(Hash)
+      flags = View.apply_v2_flag(flags || builder_flags, components, force: has_components)
+      data = data.merge({ components: components })
+      data[:flags] = flags unless flags.nil?
+      RestClient.post(encode_url(wait, thread_id, with_components: components.any?), data.to_json, content_type: :json)
+    end
+
+    def post_multipart(builder, components, wait, thread_id, flags: nil, has_components: false)
+      components = View.component_payload(components)
+      data = builder.to_multipart_hash
+      builder_flags = data[:flags] if data.is_a?(Hash)
+      flags = View.apply_v2_flag(flags || builder_flags, components, force: has_components)
+      data[:components] = components if components.any?
+      data[:flags] = flags unless flags.nil?
+      RestClient.post(encode_url(wait, thread_id, with_components: components.any?), data.compact)
+    end
+
+    def generate_url(id, token)
+      "https://discord.com/api/v9/webhooks/#{id}/#{token}"
+    end
+
+    def encode_url(wait, thread_id, with_components: false)
+      uri = URI.parse(@url)
+
+      # NOTE: We have to use string keys here, since URI#decode_www_form returns
+      # string keys, and keys with different types are treated as array query params
+      # and appended to the query params twice.
+      query = {
+        'wait' => wait,
+        'thread_id' => thread_id,
+        'with_components' => (with_components ? true : nil),
+        **URI.decode_www_form(uri.query || '').to_h
+      }
+
+      query = URI.encode_www_form(query.compact)
+      uri.query = query unless query.empty?
+      uri.to_s
+    end
+  end
+end

data/lib/onyxcord/webhooks/embeds.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+module OnyxCord::Webhooks
+  # An embed is a multipart-style attachment to a webhook message that can have a variety of different purposes and
+  # appearances.
+  class Embed
+    def initialize(title: nil, description: nil, url: nil, timestamp: nil, colour: nil, color: nil, footer: nil,
+                   image: nil, thumbnail: nil, video: nil, provider: nil, author: nil, fields: [])
+      @title = title
+      @description = description
+      @url = url
+      @timestamp = timestamp
+      self.colour = colour || color
+      @footer = footer
+      @image = image
+      @thumbnail = thumbnail
+      @video = video
+      @provider = provider
+      @author = author
+      @fields = fields
+    end
+
+    # @return [String, nil] title of the embed that will be displayed above everything else.
+    attr_accessor :title
+
+    # @return [String, nil] description for this embed
+    attr_accessor :description
+
+    # @return [String, nil] URL the title should point to
+    attr_accessor :url
+
+    # @return [Time, nil] timestamp for this embed. Will be displayed just below the title.
+    attr_accessor :timestamp
+
+    # @return [Integer, nil] the colour of the bar to the side, in decimal form
+    attr_reader :colour
+    alias_method :color, :colour
+
+    # Sets the colour of the bar to the side of the embed to something new.
+    # @param value [String, Integer, {Integer, Integer, Integer}, #to_i, nil] The colour in decimal, hexadecimal, R/G/B decimal, or nil to clear the embeds colour
+    #   form.
+    def colour=(value)
+      if value.nil?
+        @colour = nil
+      elsif value.is_a? Integer
+        raise ArgumentError, 'Embed colour must be 24-bit!' if value >= 16_777_216
+
+        @colour = value
+      elsif value.is_a? String
+        self.colour = value.delete('#').to_i(16)
+      elsif value.is_a? Array
+        raise ArgumentError, 'Colour tuple must have three values!' if value.length != 3
+
+        self.colour = (value[0] << 16) | (value[1] << 8) | value[2]
+      else
+        self.colour = value.to_i
+      end
+    end
+
+    alias_method :color=, :colour=
+
+    # @example Add a footer to an embed
+    #   embed.footer = OnyxCord::Webhooks::EmbedFooter.new(text: 'Hello', icon_url: 'https://i.imgur.com/j69wMDu.jpg')
+    # @return [EmbedFooter, nil] footer for this embed
+    attr_accessor :footer
+
+    # @see EmbedImage
+    # @example Add a image to an embed
+    #   embed.image = OnyxCord::Webhooks::EmbedImage.new(url: 'https://i.imgur.com/PcMltU7.jpg')
+    # @return [EmbedImage, nil] image for this embed
+    attr_accessor :image
+
+    # @see EmbedThumbnail
+    # @example Add a thumbnail to an embed
+    #   embed.thumbnail = OnyxCord::Webhooks::EmbedThumbnail.new(url: 'https://i.imgur.com/xTG3a1I.jpg')
+    # @return [EmbedThumbnail, nil] thumbnail for this embed
+    attr_accessor :thumbnail
+
+    # @see EmbedAuthor
+    # @example Add a author to an embed
+    #   embed.author = OnyxCord::Webhooks::EmbedAuthor.new(name: 'Gustavo S.', url: 'https://github.com/kruldevb')
+    # @return [EmbedAuthor, nil] author for this embed
+    attr_accessor :author
+
+    # Add a field object to this embed.
+    # @param field [EmbedField] The field to add.
+    def <<(field)
+      @fields << field
+    end
+
+    # Convenience method to add a field to the embed without having to create one manually.
+    # @see EmbedField
+    # @example Add a field to an embed, conveniently
+    #   embed.add_field(name: 'A field', value: "The field's content")
+    # @param name [String] The field's name
+    # @param value [String] The field's value
+    # @param inline [true, false] Whether the field should be inline
+    def add_field(name: nil, value: nil, inline: nil)
+      self << EmbedField.new(name: name, value: value, inline: inline)
+    end
+
+    # @return [Array<EmbedField>] the fields attached to this embed.
+    attr_accessor :fields
+
+    # @return [Hash] a hash representation of this embed, to be converted to JSON.
+    def to_hash
+      {
+        title: @title,
+        description: @description,
+        url: @url,
+        timestamp: @timestamp&.utc&.iso8601,
+        color: @colour,
+        footer: @footer&.to_hash,
+        image: @image&.to_hash,
+        thumbnail: @thumbnail&.to_hash,
+        video: @video&.to_hash,
+        provider: @provider&.to_hash,
+        author: @author&.to_hash,
+        fields: @fields.map(&:to_hash)
+      }
+    end
+  end
+
+  # An embed's footer will be displayed at the very bottom of an embed, together with the timestamp. An icon URL can be
+  # set together with some text to be displayed.
+  class EmbedFooter
+    # @return [String, nil] text to be displayed in the footer
+    attr_accessor :text
+
+    # @return [String, nil] URL to an icon to be showed alongside the text
+    attr_accessor :icon_url
+
+    # Creates a new footer object.
+    # @param text [String, nil] The text to be displayed in the footer.
+    # @param icon_url [String, nil] The URL to an icon to be showed alongside the text.
+    def initialize(text: nil, icon_url: nil)
+      @text = text
+      @icon_url = icon_url
+    end
+
+    # @return [Hash] a hash representation of this embed footer, to be converted to JSON.
+    def to_hash
+      {
+        text: @text,
+        icon_url: @icon_url
+      }
+    end
+  end
+
+  # An embed's image will be displayed at the bottom, in large format. It will replace a footer icon URL if one is set.
+  class EmbedImage
+    # @return [String, nil] URL of the image
+    attr_accessor :url
+
+    # Creates a new image object.
+    # @param url [String, nil] The URL of the image.
+    def initialize(url: nil)
+      @url = url
+    end
+
+    # @return [Hash] a hash representation of this embed image, to be converted to JSON.
+    def to_hash
+      {
+        url: @url
+      }
+    end
+  end
+
+  # An embed's thumbnail will be displayed at the right of the message, next to the description and fields. When clicked
+  # it will point to the embed URL.
+  class EmbedThumbnail
+    # @return [String, nil] URL of the thumbnail
+    attr_accessor :url
+
+    # Creates a new thumbnail object.
+    # @param url [String, nil] The URL of the thumbnail.
+    def initialize(url: nil)
+      @url = url
+    end
+
+    # @return [Hash] a hash representation of this embed thumbnail, to be converted to JSON.
+    def to_hash
+      {
+        url: @url
+      }
+    end
+  end
+
+  # An embed's author will be shown at the top to indicate who "authored" the particular event the webhook was sent for.
+  class EmbedAuthor
+    # @return [String, nil] name of the author
+    attr_accessor :name
+
+    # @return [String, nil] URL the name should link to
+    attr_accessor :url
+
+    # @return [String, nil] URL of the icon to be displayed next to the author
+    attr_accessor :icon_url
+
+    # Creates a new author object.
+    # @param name [String, nil] The name of the author.
+    # @param url [String, nil] The URL the name should link to.
+    # @param icon_url [String, nil] The URL of the icon to be displayed next to the author.
+    def initialize(name: nil, url: nil, icon_url: nil)
+      @name = name
+      @url = url
+      @icon_url = icon_url
+    end
+
+    # @return [Hash] a hash representation of this embed author, to be converted to JSON.
+    def to_hash
+      {
+        name: @name,
+        url: @url,
+        icon_url: @icon_url
+      }
+    end
+  end
+
+  # A field is a small block of text with a header that can be relatively freely layouted with other fields.
+  class EmbedField
+    # @return [String, nil] name of the field, displayed in bold at the top of the field.
+    attr_accessor :name
+
+    # @return [String, nil] value of the field, displayed in normal text below the name.
+    attr_accessor :value
+
+    # @return [true, false] whether the field should be displayed inline with other fields.
+    attr_accessor :inline
+
+    # Creates a new field object.
+    # @param name [String, nil] The name of the field, displayed in bold at the top of the field.
+    # @param value [String, nil] The value of the field, displayed in normal text below the name.
+    # @param inline [true, false] Whether the field should be displayed inline with other fields.
+    def initialize(name: nil, value: nil, inline: false)
+      @name = name
+      @value = value
+      @inline = inline
+    end
+
+    # @return [Hash] a hash representation of this embed field, to be converted to JSON.
+    def to_hash
+      {
+        name: @name,
+        value: @value,
+        inline: @inline
+      }
+    end
+  end
+end