rubycord 1.0.0

data/lib/rubycord/webhooks/embeds.rb

@@ -0,0 +1,248 @@
+module Rubycord::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 = Rubycord::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 = Rubycord::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 = Rubycord::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 = Rubycord::Webhooks::EmbedAuthor.new(name: 'meew0', url: 'https://github.com/meew0', icon_url: 'https://avatars2.githubusercontent.com/u/3662915?v=3&s=466')
+    # @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

data/lib/rubycord/webhooks/modal.rb

@@ -0,0 +1,78 @@
+# Modal component builder.
+class Rubycord::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/rubycord/webhooks/version.rb

@@ -0,0 +1,7 @@
+# Webhook support for rubycord
+module Rubycord
+  module Webhooks
+    # The current version of rubycord-webhooks.
+    VERSION = "1.0.0" unless const_defined?(:VERSION)
+  end
+end

data/lib/rubycord/webhooks/view.rb

@@ -0,0 +1,192 @@
+# A reusable view representing a component collection, with builder methods.
+class Rubycord::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/rubycord/webhooks.rb

@@ -0,0 +1,12 @@
+require "rubycord/webhooks/version"
+require "rubycord/webhooks/embeds"
+require "rubycord/webhooks/client"
+require "rubycord/webhooks/builder"
+require "rubycord/webhooks/view"
+require "rubycord/webhooks/modal"
+
+module Rubycord
+  # Webhook client
+  module Webhooks
+  end
+end

data/lib/rubycord/websocket.rb

@@ -0,0 +1,70 @@
+require "websocket-client-simple"
+
+# The WSCS module which we're hooking
+# @see Websocket::Client::Simple::Client
+module WebSocket::Client::Simple
+  # Patch to the WSCS class to allow reading the internal thread
+  class Client
+    # @return [Thread] the internal thread this client is using for the event loop.
+    attr_reader :thread
+  end
+end
+
+module Rubycord
+  # Utility wrapper class that abstracts an instance of WSCS. Useful should we decide that WSCS isn't good either -
+  # in that case we can just switch to something else
+  class WebSocket
+    attr_reader :open_handler, :message_handler, :close_handler, :error_handler
+
+    # Create a new WebSocket and connect to the given endpoint.
+    # @param endpoint [String] Where to connect to.
+    # @param open_handler [#call] The handler that should be called when the websocket has opened successfully.
+    # @param message_handler [#call] The handler that should be called when the websocket receives a message. The
+    #   handler can take one parameter which will have a `data` attribute for normal messages and `code` and `data` for
+    #   close frames.
+    # @param close_handler [#call] The handler that should be called when the websocket is closed due to an internal
+    #   error. The error will be passed as the first parameter to the handler.
+    # @param error_handler [#call] The handler that should be called when an error occurs in another handler. The error
+    #   will be passed as the first parameter to the handler.
+    def initialize(endpoint, open_handler, message_handler, close_handler, error_handler)
+      Rubycord::LOGGER.debug "Using WSCS version: #{::WebSocket::Client::Simple::VERSION}"
+
+      @open_handler = open_handler
+      @message_handler = message_handler
+      @close_handler = close_handler
+      @error_handler = error_handler
+
+      instance = self # to work around WSCS's weird way of handling blocks
+
+      @client = ::WebSocket::Client::Simple.connect(endpoint) do |ws|
+        ws.on(:open) { instance.open_handler.call }
+        ws.on(:message) do |msg|
+          # If the message has a code attribute, it is in reality a close message
+          if msg.code
+            instance.close_handler.call(msg)
+          else
+            instance.message_handler.call(msg.data)
+          end
+        end
+        ws.on(:close) { |err| instance.close_handler.call(err) }
+        ws.on(:error) { |err| instance.error_handler.call(err) }
+      end
+    end
+
+    # Send data over this WebSocket
+    # @param data [String] What to send
+    def send(data)
+      @client.send(data)
+    end
+
+    # Close the WebSocket connection
+    def close
+      @client.close
+    end
+
+    # @return [Thread] the internal WSCS thread
+    def thread
+      @client.thread
+    end
+  end
+end