discordrb-webhooks 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6e33e989ed634c58e7bec8ee4b270addbaf2afb1
+  data.tar.gz: d75947052d5ba2f4047622e65d3a83a829cfbc05
+SHA512:
+  metadata.gz: '0093a27a7257c39ebb0f27d756be7c682e58a2479d7ec6a7bdaca72a1d251d36794ec5b503cd4ddc1d738f5fa91ae2170aa69fd1c334a944eac73078e54e96f9'
+  data.tar.gz: 5781b554604a09ea88afb284c4cb522c16581ac4855974f71c54462a67ae89cce117f5c23c62ba2ba5bc0be3d1198e5ae346036b3b58e9207d7f50e06ee6540d

data/lib/discordrb/webhooks.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'discordrb/webhooks/version'
+require 'discordrb/webhooks/embeds'
+require 'discordrb/webhooks/client'
+require 'discordrb/webhooks/builder'
+
+module Discordrb
+  # Webhook client
+  module Webhooks
+  end
+end

data/lib/discordrb/webhooks/builder.rb

@@ -0,0 +1,91 @@
+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: [])
+      @content = content
+      @username = username
+      @avatar_url = avatar_url
+      @tts = tts
+      @file = file
+      @embeds = embeds
+    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
+
+    # 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 = Discordrb::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
+
+    # @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 [Hash] a hash representation of the created message, for JSON format.
+    def to_json_hash
+      {
+        content: @content,
+        username: @username,
+        avatar_url: @avatar_url,
+        tts: @tts,
+        embeds: @embeds.map(&:to_hash)
+      }
+    end
+
+    # @return [Hash] a hash representation of the created message, for multipart format.
+    def to_multipart_hash
+      {
+        content: @content,
+        username: @username,
+        avatar_url: @avatar_url,
+        tts: @tts,
+        file: @file
+      }
+    end
+  end
+end

data/lib/discordrb/webhooks/client.rb

@@ -0,0 +1,72 @@
+require 'rest-client'
+require 'json'
+
+require 'discordrb/webhooks/builder'
+
+module Discordrb::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 = if url
+               url
+             else
+               generate_url(id, token)
+             end
+    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.
+    # @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 = Discordrb::Webhooks::Builder.new # ...
+    #   client.execute(builder)
+    # @example Execute the webhook by building a new message
+    #   client.execute do |builder|
+    #     builder.content = 'Testing'
+    #     builder.username = 'discordrb'
+    #     builder.add_embed do |embed|
+    #       embed.timestamp = Time.now
+    #       embed.title = 'Testing'
+    #       embed.image = Discordrb::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)
+      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 ||= Builder.new
+
+      yield builder if block_given?
+
+      if builder.file
+        post_multipart(builder, wait)
+      else
+        post_json(builder, wait)
+      end
+    end
+
+    private
+
+    def post_json(builder, wait)
+      RestClient.post(@url + (wait ? '?wait=true' : ''), builder.to_json_hash.to_json, content_type: :json)
+    end
+
+    def post_multipart(builder, wait)
+      RestClient.post(@url + (wait ? '?wait=true' : ''), builder.to_multipart_hash)
+    end
+
+    def generate_url(id, token)
+      "https://discordapp.com/api/v6/webhooks/#{id}/#{token}"
+    end
+  end
+end

data/lib/discordrb/webhooks/embeds.rb

@@ -0,0 +1,220 @@
+module Discordrb::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
+      @colour = colour || color
+      @footer = footer
+      @image = image
+      @thumbnail = thumbnail
+      @video = video
+      @provider = provider
+      @author = author
+      @fields = fields
+    end
+
+    # The title of this embed that will be displayed above everything else.
+    # @return [String]
+    attr_accessor :title
+
+    # The description for this embed.
+    # @return [String]
+    attr_accessor :description
+
+    # The URL the title should point to.
+    # @return [String]
+    attr_accessor :url
+
+    # The timestamp for this embed. Will be displayed just below the title.
+    # @return [Time]
+    attr_accessor :timestamp
+
+    # @return [Integer] 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 [Integer, String, {Integer, Integer, Integer}] The colour in decimal, hexadecimal, or R/G/B decimal
+    #   form.
+    def colour=(value)
+      if 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]
+      end
+    end
+
+    alias_method :color=, :colour=
+
+    # The footer for this embed.
+    # @example Add a footer to an embed
+    #   embed.footer = Discordrb::Webhooks::EmbedFooter.new(text: 'Hello', icon_url: 'https://i.imgur.com/j69wMDu.jpg')
+    # @return [EmbedFooter]
+    attr_accessor :footer
+
+    # The image for this embed.
+    # @see EmbedImage
+    # @example Add a image to an embed
+    #   embed.image = Discordrb::Webhooks::EmbedImage.new(url: 'https://i.imgur.com/PcMltU7.jpg')
+    # @return [EmbedImage]
+    attr_accessor :image
+
+    # The thumbnail for this embed.
+    # @see EmbedThumbnail
+    # @example Add a thumbnail to an embed
+    #   embed.thumbnail = Discordrb::Webhooks::EmbedThumbnail.new(url: 'https://i.imgur.com/xTG3a1I.jpg')
+    # @return [EmbedThumbnail]
+    attr_accessor :thumbnail
+
+    # The author for this embed.
+    # @see EmbedAuthor
+    # @example Add a author to an embed
+    #   embed.author = Discordrb::Webhooks::EmbedAuthor.new(name: 'meew0', url: 'https://github.com/meew0', icon_url: 'https://avatars2.githubusercontent.com/u/3662915?v=3&s=466')
+    # @return [EmbedAuthor]
+    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 inlined
+    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_reader :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 && @timestamp.utc.iso8601,
+        color: @colour,
+        footer: @footer && @footer.to_hash,
+        image: @image && @image.to_hash,
+        thumbnail: @thumbnail && @thumbnail.to_hash,
+        video: @video && @video.to_hash,
+        provider: @provider && @provider.to_hash,
+        author: @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
+    # 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
+    # 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
+    # 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
+    # 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
+    # Creates a new field object.
+    # @param name [String, nil] The name of the field, displayed in bold at the top.
+    # @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 in-line with other fields.
+    def initialize(name: nil, value: nil, inline: nil)
+      @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/discordrb/webhooks/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Webhook support for discordrb
+module Discordrb
+  module Webhooks
+    # The current version of discordrb-webhooks.
+    VERSION = '0.1.0'.freeze
+  end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: discordrb-webhooks
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- meew0
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-01-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A client for Discord's webhooks to fit alongside [discordrb](https://rubygems.org/gems/discordrb).
+email:
+- ''
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/discordrb/webhooks.rb
+- lib/discordrb/webhooks/builder.rb
+- lib/discordrb/webhooks/client.rb
+- lib/discordrb/webhooks/embeds.rb
+- lib/discordrb/webhooks/version.rb
+homepage: https://github.com/meew0/discordrb
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.10
+signing_key: 
+specification_version: 4
+summary: Webhook client for discordrb
+test_files: []
+has_rdoc: