discordrb-webhooks 3.4.3 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79b0d69e96092e442b9602a6dd69088579af024ec84480209754831dcd0e39f8
-  data.tar.gz: 17ddc58683c197db7bb8afc5153e3587bef92652eecb9a2430d7101356f730a4
+  metadata.gz: ac23678014708b3612c2b64182fc560e28fffaff546fe32068b6c80f92241a49
+  data.tar.gz: 1af3c1de510f8262df3074bbcb28af659ad233c0447feab33709ccafbb99bf9b
 SHA512:
-  metadata.gz: 79f43ebe587deac54faf3745839fd0a39e13c62d9f8f00bcffb6f6aa23234d0fcec7b3b7be2d116cf4cb351d208837c8955b1d79e0382a1d42f94e3489c8c35f
-  data.tar.gz: c697972d1a676d5f704f7d1b3f4160daeb1e0d72ee8841122e974b30f85ce63176195ef4fbf4258c6eb1f0be5b39bfe6c84effa9ba8bab3ad82f4d4fc5680805
+  metadata.gz: eb90480b721262fe38147e7f117ebd102ab05f9dc5435ef4fdf2263c0c4bb9b0886077f10ebb8f4b73db57e8cd751bad1e97f90917c5c3f4ad9b6714fd92212b
+  data.tar.gz: '0678b594744221149421bb72ed219ee9b916aca0e2ad58f4f7002fc94627d3d9aed6bcbaaca73cf8116eed7a0b7a5a5dd3f0c8a71cf5183a256d6af6471fe61d'

data/lib/discordrb/webhooks/builder.rb

@@ -5,13 +5,14 @@ require 'discordrb/webhooks/embeds'
 module Discordrb::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: [])
+    def initialize(content: '', username: nil, avatar_url: nil, tts: false, file: nil, embeds: [], allowed_mentions: nil)
       @content = content
       @username = username
       @avatar_url = avatar_url
       @tts = tts
       @file = file
       @embeds = embeds
+      @allowed_mentions = allowed_mentions
     end
 
     # The content of the message. May be 2000 characters long at most.
@@ -70,6 +71,10 @@ module Discordrb::Webhooks
     # @return [Array<Embed>] the embeds attached to this message.
     attr_reader :embeds
 
+    # @return [Discordrb::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 [Hash] a hash representation of the created message, for JSON format.
     def to_json_hash
       {
@@ -77,7 +82,8 @@ module Discordrb::Webhooks
         username: @username,
         avatar_url: @avatar_url,
         tts: @tts,
-        embeds: @embeds.map(&:to_hash)
+        embeds: @embeds.map(&:to_hash),
+        allowed_mentions: @allowed_mentions&.to_hash
       }
     end
 
@@ -88,7 +94,8 @@ module Discordrb::Webhooks
         username: @username,
         avatar_url: @avatar_url,
         tts: @tts,
-        file: @file
+        file: @file,
+        allowed_mentions: @allowed_mentions&.to_hash
       }
     end
   end

data/lib/discordrb/webhooks/client.rb

@@ -38,33 +38,97 @@ module Discordrb::Webhooks
     #     end
     #   end
     # @return [RestClient::Response] the response returned by Discord.
-    def execute(builder = nil, wait = false)
+    def execute(builder = nil, wait = false, components = nil)
       raise TypeError, 'builder needs to be nil or like a Discordrb::Webhooks::Builder!' unless
-        builder.respond_to?(:file) && builder.respond_to?(:to_multipart_hash) || builder.respond_to?(:to_json_hash) || builder.nil?
+        (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 if block_given?
+      yield(builder, view) if block_given?
+
+      components ||= view
 
       if builder.file
-        post_multipart(builder, wait)
+        post_multipart(builder, components, wait)
       else
-        post_json(builder, wait)
+        post_json(builder, components, wait)
       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]
+    # @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)
+      builder ||= Builder.new
+
+      yield builder if block_given?
+
+      data = builder.to_json_hash.merge({ content: content, embeds: embeds, allowed_mentions: allowed_mentions }.compact)
+      RestClient.patch("#{@url}/messages/#{message_id}", 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
 
-    def post_json(builder, wait)
-      RestClient.post(@url + (wait ? '?wait=true' : ''), builder.to_json_hash.to_json, content_type: :json)
+    # 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)
+      data = builder.to_json_hash.merge({ components: components.to_a })
+      RestClient.post(@url + (wait ? '?wait=true' : ''), data.to_json, content_type: :json)
     end
 
-    def post_multipart(builder, wait)
-      RestClient.post(@url + (wait ? '?wait=true' : ''), builder.to_multipart_hash)
+    def post_multipart(builder, components, wait)
+      data = builder.to_multipart_hash.merge({ components: components.to_a })
+      RestClient.post(@url + (wait ? '?wait=true' : ''), data)
     end
 
     def generate_url(id, token)
-      "https://discord.com/api/v6/webhooks/#{id}/#{token}"
+      "https://discord.com/api/v8/webhooks/#{id}/#{token}"
     end
   end
 end

data/lib/discordrb/webhooks/embeds.rb

@@ -51,7 +51,7 @@ module Discordrb::Webhooks
       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]
+        self.colour = (value[0] << 16) | (value[1] << 8) | value[2]
       else
         self.colour = value.to_i
       end

data/lib/discordrb/webhooks/modal.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# Modal component builder.
+class Discordrb::Webhooks::Modal
+  # A mapping of names to types of components usable in a modal.
+  COMPONENT_TYPES = {
+    action_row: 1,
+    text_input: 4
+  }.freeze
+
+  # This builder is used when constructing an ActionRow. All current components must be within an action row, but this can
+  # change in the future. A message can have 5 action rows, each action row can hold a weight of 5. Buttons have a weight of 1,
+  # and dropdowns have a weight of 5.
+  class RowBuilder
+    # A mapping of short names to types of input styles. `short` is a single line where `paragraph` is a block.
+    TEXT_INPUT_STYLES = {
+      short: 1,
+      paragraph: 2
+    }.freeze
+
+    # @!visibility private
+    def initialize
+      @components = []
+    end
+
+    # Add a text input to this action row.
+    # @param style [Symbol, Integer] The text input's style type. See {TEXT_INPUT_STYLES}
+    # @param custom_id [String] Custom IDs are used to pass state to the events that are raised from interactions.
+    #  There is a limit of 100 characters to each custom_id.
+    # @param label [String, nil] The text label for the field.
+    # @param min_length [Integer, nil] The minimum input length for a text input, min 0, max 4000.
+    # @param max_length [Integer, nil] The maximum input length for a text input, min 1, max 4000.
+    # @param required [true, false, nil] Whether this component is required to be filled, default true.
+    # @param value [String, nil] A pre-filled value for this component, max 4000 characters.
+    # @param placeholder [String, nil] Custom placeholder text if the input is empty, max 100 characters
+    def text_input(style:, custom_id:, label: nil, min_length: nil, max_length: nil, required: nil, value: nil, placeholder: nil)
+      style = TEXT_INPUT_STYLES[style] || style
+
+      @components << {
+        style: style,
+        custom_id: custom_id,
+        type: COMPONENT_TYPES[:text_input],
+        label: label,
+        min_length: min_length,
+        max_length: max_length,
+        required: required,
+        value: value,
+        placeholder: placeholder
+      }
+    end
+
+    # @!visibility private
+    def to_h
+      { type: COMPONENT_TYPES[:action_row], components: @components }
+    end
+  end
+
+  attr_reader :rows
+
+  def initialize
+    @rows = []
+
+    yield self if block_given?
+  end
+
+  # Add a new ActionRow to the view
+  # @yieldparam [RowBuilder]
+  def row
+    new_row = RowBuilder.new
+
+    yield new_row
+
+    @rows << new_row
+  end
+
+  # @!visibility private
+  def to_a
+    @rows.map(&:to_h)
+  end
+end

data/lib/discordrb/webhooks/version.rb

@@ -4,6 +4,6 @@
 module Discordrb
   module Webhooks
     # The current version of discordrb-webhooks.
-    VERSION = '3.4.3'
+    VERSION = '3.5.0'
   end
 end

data/lib/discordrb/webhooks/view.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+# A reusable view representing a component collection, with builder methods.
+class Discordrb::Webhooks::View
+  # Possible button style names and values.
+  BUTTON_STYLES = {
+    primary: 1,
+    secondary: 2,
+    success: 3,
+    danger: 4,
+    link: 5
+  }.freeze
+
+  # Component types.
+  # @see https://discord.com/developers/docs/interactions/message-components#component-types
+  COMPONENT_TYPES = {
+    action_row: 1,
+    button: 2,
+    string_select: 3,
+    # text_input: 4, # (defined in modal.rb)
+    user_select: 5,
+    role_select: 6,
+    mentionable_select: 7,
+    channel_select: 8
+  }.freeze
+
+  # This builder is used when constructing an ActionRow. All current components must be within an action row, but this can
+  # change in the future. A message can have 5 action rows, each action row can hold a weight of 5. Buttons have a weight of 1,
+  # and dropdowns have a weight of 5.
+  class RowBuilder
+    # @!visibility private
+    def initialize
+      @components = []
+    end
+
+    # Add a button to this action row.
+    # @param style [Symbol, Integer] The button's style type. See {BUTTON_STYLES}
+    # @param label [String, nil] The text label for the button. Either a label or emoji must be provided.
+    # @param emoji [#to_h, String, Integer] An emoji ID, or unicode emoji to attach to the button. Can also be a object
+    #   that responds to `#to_h` which returns a hash in the format of `{ id: Integer, name: string }`.
+    # @param custom_id [String] Custom IDs are used to pass state to the events that are raised from interactions.
+    #   There is a limit of 100 characters to each custom_id.
+    # @param disabled [true, false] Whether this button is disabled and shown as greyed out.
+    # @param url [String, nil] The URL, when using a link style button.
+    def button(style:, label: nil, emoji: nil, custom_id: nil, disabled: nil, url: nil)
+      style = BUTTON_STYLES[style] || style
+
+      emoji = case emoji
+              when Integer, String
+                emoji.to_i.positive? ? { id: emoji } : { name: emoji }
+              else
+                emoji.to_h
+              end
+
+      @components << { type: COMPONENT_TYPES[:button], label: label, emoji: emoji, style: style, custom_id: custom_id, disabled: disabled, url: url }
+    end
+
+    # Add a select string to this action row.
+    # @param custom_id [String] Custom IDs are used to pass state to the events that are raised from interactions.
+    #   There is a limit of 100 characters to each custom_id.
+    # @param options [Array<Hash>] Options that can be selected in this menu. Can also be provided via the yielded builder.
+    # @param placeholder [String, nil] Default text to show when no entries are selected.
+    # @param min_values [Integer, nil] The minimum amount of values a user must select.
+    # @param max_values [Integer, nil] The maximum amount of values a user can select.
+    # @param disabled [true, false, nil] Grey out the component to make it unusable.
+    # @yieldparam builder [SelectMenuBuilder]
+    def string_select(custom_id:, options: [], placeholder: nil, min_values: nil, max_values: nil, disabled: nil)
+      builder = SelectMenuBuilder.new(custom_id, options, placeholder, min_values, max_values, disabled, select_type: :string_select)
+
+      yield builder if block_given?
+
+      @components << builder.to_h
+    end
+
+    alias_method :select_menu, :string_select
+
+    # Add a select user to this action row.
+    # @param custom_id [String] Custom IDs are used to pass state to the events that are raised from interactions.
+    #   There is a limit of 100 characters to each custom_id.
+    # @param placeholder [String, nil] Default text to show when no entries are selected.
+    # @param min_values [Integer, nil] The minimum amount of values a user must select.
+    # @param max_values [Integer, nil] The maximum amount of values a user can select.
+    # @param disabled [true, false, nil] Grey out the component to make it unusable.
+    def user_select(custom_id:, placeholder: nil, min_values: nil, max_values: nil, disabled: nil)
+      @components << SelectMenuBuilder.new(custom_id, [], placeholder, min_values, max_values, disabled, select_type: :user_select).to_h
+    end
+
+    # Add a select role to this action row.
+    # @param custom_id [String] Custom IDs are used to pass state to the events that are raised from interactions.
+    #   There is a limit of 100 characters to each custom_id.
+    # @param placeholder [String, nil] Default text to show when no entries are selected.
+    # @param min_values [Integer, nil] The minimum amount of values a user must select.
+    # @param max_values [Integer, nil] The maximum amount of values a user can select.
+    # @param disabled [true, false, nil] Grey out the component to make it unusable.
+    def role_select(custom_id:, placeholder: nil, min_values: nil, max_values: nil, disabled: nil)
+      @components << SelectMenuBuilder.new(custom_id, [], placeholder, min_values, max_values, disabled, select_type: :role_select).to_h
+    end
+
+    # Add a select mentionable to this action row.
+    # @param custom_id [String] Custom IDs are used to pass state to the events that are raised from interactions.
+    #   There is a limit of 100 characters to each custom_id.
+    # @param placeholder [String, nil] Default text to show when no entries are selected.
+    # @param min_values [Integer, nil] The minimum amount of values a user must select.
+    # @param max_values [Integer, nil] The maximum amount of values a user can select.
+    # @param disabled [true, false, nil] Grey out the component to make it unusable.
+    def mentionable_select(custom_id:, placeholder: nil, min_values: nil, max_values: nil, disabled: nil)
+      @components << SelectMenuBuilder.new(custom_id, [], placeholder, min_values, max_values, disabled, select_type: :mentionable_select).to_h
+    end
+
+    # Add a select channel to this action row.
+    # @param custom_id [String] Custom IDs are used to pass state to the events that are raised from interactions.
+    #   There is a limit of 100 characters to each custom_id.
+    # @param placeholder [String, nil] Default text to show when no entries are selected.
+    # @param min_values [Integer, nil] The minimum amount of values a user must select.
+    # @param max_values [Integer, nil] The maximum amount of values a user can select.
+    # @param disabled [true, false, nil] Grey out the component to make it unusable.
+    def channel_select(custom_id:, placeholder: nil, min_values: nil, max_values: nil, disabled: nil)
+      @components << SelectMenuBuilder.new(custom_id, [], placeholder, min_values, max_values, disabled, select_type: :channel_select).to_h
+    end
+
+    # @!visibility private
+    def to_h
+      { type: COMPONENT_TYPES[:action_row], components: @components }
+    end
+  end
+
+  # A builder to assist in adding options to select menus.
+  class SelectMenuBuilder
+    # @!visibility hidden
+    def initialize(custom_id, options = [], placeholder = nil, min_values = nil, max_values = nil, disabled = nil, select_type: :string_select)
+      @custom_id = custom_id
+      @options = options
+      @placeholder = placeholder
+      @min_values = min_values
+      @max_values = max_values
+      @disabled = disabled
+      @select_type = select_type
+    end
+
+    # Add an option to this select menu.
+    # @param label [String] The title of this option.
+    # @param value [String] The value that this option represents.
+    # @param description [String, nil] An optional description of the option.
+    # @param emoji [#to_h, String, Integer] An emoji ID, or unicode emoji to attach to the button. Can also be a object
+    #   that responds to `#to_h` which returns a hash in the format of `{ id: Integer, name: string }`.
+    # @param default [true, false, nil] Whether this is the default selected option.
+    def option(label:, value:, description: nil, emoji: nil, default: nil)
+      emoji = case emoji
+              when Integer, String
+                emoji.to_i.positive? ? { id: emoji } : { name: emoji }
+              else
+                emoji.to_h
+              end
+
+      @options << { label: label, value: value, description: description, emoji: emoji, default: default }
+    end
+
+    # @!visibility private
+    def to_h
+      {
+        type: COMPONENT_TYPES[@select_type],
+        options: @options,
+        placeholder: @placeholder,
+        min_values: @min_values,
+        max_values: @max_values,
+        custom_id: @custom_id,
+        disabled: @disabled
+      }
+    end
+  end
+
+  attr_reader :rows
+
+  def initialize
+    @rows = []
+
+    yield self if block_given?
+  end
+
+  # Add a new ActionRow to the view
+  # @yieldparam [RowBuilder]
+  def row
+    new_row = RowBuilder.new
+
+    yield new_row
+
+    @rows << new_row
+  end
+
+  # @!visibility private
+  def to_a
+    @rows.map(&:to_h)
+  end
+end

data/lib/discordrb/webhooks.rb

@@ -4,6 +4,8 @@ require 'discordrb/webhooks/version'
 require 'discordrb/webhooks/embeds'
 require 'discordrb/webhooks/client'
 require 'discordrb/webhooks/builder'
+require 'discordrb/webhooks/view'
+require 'discordrb/webhooks/modal'
 
 module Discordrb
   # Webhook client

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: discordrb-webhooks
 version: !ruby/object:Gem::Version
-  version: 3.4.3
+  version: 3.5.0
 platform: ruby
 authors:
 - meew0
@@ -36,11 +36,14 @@ files:
 - lib/discordrb/webhooks/builder.rb
 - lib/discordrb/webhooks/client.rb
 - lib/discordrb/webhooks/embeds.rb
+- lib/discordrb/webhooks/modal.rb
 - lib/discordrb/webhooks/version.rb
+- lib/discordrb/webhooks/view.rb
 homepage: https://github.com/shardlab/discordrb
 licenses:
 - MIT
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -49,7 +52,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="