async-discord 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33834a7af00dffadb4f4c2c050e62dda6aa9823401a7be3814616422bce948a1
-  data.tar.gz: 40e8682837b6325b3d1a14bdb8913b535cccc96d5cd569e81822a63851275850
+  metadata.gz: fda03ce79f4fbac7dac03a5290af0a07c7a159fa160a4fa7dfd3ec072d214f38
+  data.tar.gz: 1ebd9eb42de4f3d916820797e45d49a3657ac77c021e9099137cde15134359dc
 SHA512:
-  metadata.gz: d07684c7f494a3cc8893b345190d2fd495b5ec57251be6a11f158e22c12aeade6a6f975ae078287bc7e1171db4adaf942f426009a685caf39df731725f0ad96d
-  data.tar.gz: d316e91be104bf9634f4ec8242c7c9f4410e0a823de3627c62232d23c7c7c85cf099c158cfb3e7adba9150d1ce1808bdd0e3b54a62774a5f18414891f5e8415e
+  metadata.gz: bb9aaa5be5d7e133bff407105dada36e5bd89accd5c8fbd2c32fa6ff114daeb5445247bdfce906e3c1b077c988943b64b615c6c5f886113c800856c995ff223c
+  data.tar.gz: 246bce63ba164bd1a3621045d71569aa47f50339d657249c019b67f3b9d73d9bcee41fd2d4d6155a036e3b94108ba3d41f5d218c0bc7f1d7da0dac463c9f0b6c

data/lib/async/discord/channels.rb

@@ -1,11 +1,21 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
 require_relative "representation"
 
 module Async
 	module Discord
+		# Represents a message in a channel.
 		class Message < Representation
 		end
 		
+		# Represents a channel in a guild.
 		class Channel < Representation
+			# Send a message to this channel.
+			#
+			# @parameter content [String] The content of the message.
 			def send_message(content)
 				payload = {
 					content: content
@@ -14,20 +24,32 @@ module Async
 				Message.post(@resource.with(path: "messages"), payload)
 			end
 			
+			# The unique identifier for this channel.
 			def id
 				self.value[:id]
 			end
 			
+			# Whether this channel is a text channel.
+			#
+			# @returns [Boolean] if this channel is a text channel.
 			def text?
 				self.value[:type] == 0
 			end
 			
+			# Whether this channel is a voice channel.
+			#
+			# @returns [Boolean] if this channel is a voice channel.
 			def voice?
 				self.value[:type] == 2
 			end
 		end
 		
+		# Represents a collection of channels.
 		class Channels < Representation
+			# Enumerate over each channel.
+			#
+			# @yields {|channel| ...}
+			# 	@parameter channel [Channel] The channel.
 			def each(&block)
 				return to_enum unless block_given?
 				
@@ -38,6 +60,9 @@ module Async
 				end
 			end
 			
+			# Convert this collection to an array.
+			#
+			# @returns [Array(Channel)] an array of channels.
 			def to_a
 				each.to_a
 			end

data/lib/async/discord/client.rb

@@ -1,36 +1,28 @@
-# frozen_string_literals: true
-#
-# Copyright, 2019, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# 
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-# 
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-# 
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-# THE SOFTWARE.
+# frozen_string_literal: true
 
-require_relative 'representation'
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
 
-require_relative 'guilds'
-require_relative 'gateway'
+require_relative "representation"
+
+require_relative "guilds"
+require_relative "gateway"
 
 module Async
 	module Discord
+		# A client for interacting with Discord.
 		class Client < Async::REST::Resource
+			# The default endpoint for Discord.
 			ENDPOINT = Async::HTTP::Endpoint.parse("https://discord.com/api/v10/")
+			
+			# The default user agent for this client.
 			USER_AGENT = "#{self.name} (https://github.com/socketry/async-discord, v#{Async::Discord::VERSION})"
 			
+			# Authenticate the client, either with a bot or bearer token.
+			#
+			# @parameter bot [String] The bot token.
+			# @parameter bearer [String] The bearer token.
+			# @returns [Client] a new client with the given authentication.
 			def authenticated(bot: nil, bearer: nil)
 				headers = {}
 				
@@ -47,14 +39,17 @@ module Async
 				return self.with(headers: headers)
 			end
 			
+			# @returns [Guilds] a collection of guilds the bot is a member of.
 			def guilds
 				Guilds.new(self.with(path: "users/@me/guilds"))
 			end
 			
+			# @returns [Gateway] the gateway for the bot.
 			def gateway
 				Gateway.new(self.with(path: "gateway/bot"))
 			end
 			
+			# @returns [Channel] a channel by its unique identifier.
 			def channel(id)
 				Channel.new(self.with(path: "channels/#{id}"))
 			end

data/lib/async/discord/gateway.rb

@@ -1,9 +1,15 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
 require_relative "representation"
 
 require "async/websocket"
 
 module Async
 	module Discord
+		# Represents a gateway connection to Discord, which can be used to send and receive messages via a WebSocket connection.
 		class GatewayConnection < Async::WebSocket::Connection
 			# Gateway Opcodes:
 			DISPATCH = 0
@@ -19,7 +25,7 @@ module Async
 			HEARTBEAT_ACK = 11
 			REQUEST_SOUNDBOARD_SOUNDS = 31
 			
-			# Gateway Error Codes
+			# Gateway Error Codes.
 			ERROR_CODES = {
 				4000 => "UNKNOWN_ERROR",
 				4001 => "UNKNOWN_OPCODE",
@@ -37,7 +43,7 @@ module Async
 				4014 => "DISALLOWED_INTENT"
 			}
 			
-			# Guild Intents:
+			# Guild Intents.
 			module Intent
 				GUILDS = 1 << 0
 				GUILD_MEMBERS = 1 << 1
@@ -62,20 +68,24 @@ module Async
 				DIRECT_MESSAGE_POLLS = 1 << 25
 			end
 			
+			# Default intent for a bot.
 			DEFAULT_INTENT = Intent::GUILDS | Intent::GUILD_MESSAGES | Intent::DIRECT_MESSAGES
 			
+			# Default properties for a bot.
 			DEFAULT_PROPERTIES = {
 				os: RUBY_PLATFORM,
 				browser: Async::Discord.name,
 				device: Async::Discord.name,
 			}
 			
+			# Default presence for a bot.
 			DEFAULT_PRESENCE = {
 				status: "online",
 				afk: false,
 				activities: [],
 			}
 			
+			# Initialize the gateway connection.
 			def initialize(...)
 				super
 				
@@ -83,6 +93,7 @@ module Async
 				@sequence = nil
 			end
 			
+			# Close the gateway connection, including the heartbeat task.
 			def close(...)
 				if heartbeat_task = @heartbeat_task
 					@heartbeat_task = nil
@@ -92,6 +103,9 @@ module Async
 				super
 			end
 			
+			# Identify the bot with the given identity.
+			#
+			# @returns [Hash] the payload from the READY event.
 			def identify(**identity)
 				while message = self.read
 					payload = message.parse
@@ -131,6 +145,10 @@ module Async
 				end
 			end
 			
+			# Listen for events from the gateway.
+			#
+			# @yields {|payload| ...}
+			# 	@parameter payload [Hash] The parsed payload.
 			def listen
 				while message = self.read
 					payload = message.parse
@@ -153,6 +171,7 @@ module Async
 			
 			private
 			
+			# Run a heartbeat task at the given interval.
 			def run_heartbeat(duration_ms)
 				duration = duration_ms / 1000.0
 				Console.debug(self, "Running heartbeat every #{duration} seconds.")
@@ -172,19 +191,30 @@ module Async
 			end
 		end
 		
+		# Represents a gateway for the bot.
 		class Gateway < Representation
+			# The URL of the gateway, used for connecting to the WebSocket server.
 			def url
 				self.value[:url]
 			end
 			
+			# The number of shards to use.
 			def shards
 				self.value[:shards]
 			end
 			
+			# Limits associated with this bot connecting to the gateway. You should respect these limits to avoid being rate limited.
+			#
+			# @returns [Hash] the limits, including `:total`, `:remaining`, `:reset_after`, and `:max_concurrency`.
 			def session_start_limit
 				self.value[:session_start_limit]
 			end
 			
+			# Connect to the gateway, yielding the connection.
+			#
+			# @yields {|connection| ...} if a block is given.
+			# 	@parameter connection [GatewayConnection] The connection to the gateway.
+			# @returns [GatewayConnection] the connection to the gateway.
 			def connect(shard: nil, &block)
 				endpoint = Async::HTTP::Endpoint.parse(self.url, alpn_protocols: Async::HTTP::Protocol::HTTP11.names)
 				

data/lib/async/discord/guilds.rb

@@ -1,19 +1,33 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
 require_relative "representation"
 require_relative "channels"
 
 module Async
 	module Discord
+		# Represents a guild in Discord.
 		class Guild < Representation
+			# @returns [Channels] a collection of channels in this guild.
 			def channels
 				Channels.new(@resource.with(path: "channels"))
 			end
 			
+			# The unique identifier for this guild.
 			def id
 				self.value[:id]
 			end
 		end
 		
+		# Represents a collection of guilds.
 		class Guilds < Representation
+			# Enumerate over each guild.
+			#
+			# @yields {|guild| ...} if a block is given.
+			# 	@parameter guild [Guild] The guild.
+			# @returns [Enumerator] if no block is given.
 			def each(&block)
 				return to_enum unless block_given?
 				
@@ -24,9 +38,17 @@ module Async
 				end
 			end
 			
+			# Convert the collection to an array.
+			#
+			# @returns [Array(Guild)] the collection as an array.
 			def to_a
 				each.to_a
 			end
+			
+			# @returns [Boolean] if the collection is empty.
+			def empty?
+				self.value.empty?
+			end
 		end
 	end
 end

data/lib/async/discord/representation.rb

@@ -1,33 +1,18 @@
-# frozen_string_literals: true
-#
-# Copyright, 2019, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# 
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-# 
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-# 
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-# THE SOFTWARE.
+# frozen_string_literal: true
 
-require 'async/rest/representation'
-require 'async/rest/wrapper/form'
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+require "async/rest/representation"
+require "async/rest/wrapper/form"
 
 module Async
 	module Discord
+		# The default wrapper for Discord.
 		class Wrapper < Async::REST::Wrapper::JSON
 		end
 		
+		# The default representation for Discord.
 		class Representation < Async::REST::Representation[Wrapper]
 		end
 	end

data/lib/async/discord/version.rb

@@ -5,6 +5,6 @@
 
 module Async
 	module Discord
-		VERSION = "0.1.0"
+		VERSION = "0.1.1"
 	end
 end

data/lib/async/discord.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+require_relative "discord/version"
+require_relative "discord/client"
+
+# @namespace
+module Async
+	# @namespace
+	module Discord
+	end
+end
+

data/readme.md

@@ -1,3 +1,37 @@
 # Async::Discord
 
 Provides a simple `Async::REST` client for interacting with the Discord API.
+
+[![Development Status](https://github.com/socketry/async-discord/workflows/Test/badge.svg)](https://github.com/socketry/async-discord/actions?workflow=Test)
+
+## Usage
+
+Please see the [project documentation](https://socketry.github.io/async-discord/) for more details.
+
+  - [Getting Started](https://socketry.github.io/async-discord/guides/getting-started/index) - This guide explains how to create a bot for Discord using the `async-discord` gem.
+
+## Releases
+
+Please see the [project releases](https://socketry.github.io/async-discord/releases/index) for all releases.
+
+### v0.1.0
+
+  - Initial release.
+
+## Contributing
+
+We welcome contributions to this project.
+
+1.  Fork it.
+2.  Create your feature branch (`git checkout -b my-new-feature`).
+3.  Commit your changes (`git commit -am 'Add some feature'`).
+4.  Push to the branch (`git push origin my-new-feature`).
+5.  Create new Pull Request.
+
+### Developer Certificate of Origin
+
+In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
+
+### Community Guidelines
+
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.

data/releases.md

@@ -0,0 +1,5 @@
+# Releases
+
+## v0.1.0
+
+  - Initial release.

metadata

@@ -1,11 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: async-discord
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Samuel Williams
-autorequire:
 bindir: bin
 cert_chain:
 - |
@@ -37,22 +36,22 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-11-25 00:00:00.000000000 Z
+date: 2025-01-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async-rest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.19'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.19'
 - !ruby/object:Gem::Dependency
   name: async-websocket
   requirement: !ruby/object:Gem::Requirement
@@ -67,12 +66,11 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description:
-email:
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/async/discord.rb
 - lib/async/discord/channels.rb
 - lib/async/discord/client.rb
 - lib/async/discord/gateway.rb
@@ -81,12 +79,13 @@ files:
 - lib/async/discord/version.rb
 - license.md
 - readme.md
+- releases.md
 homepage: https://github.com/socketry/async-discord
 licenses:
 - MIT
 metadata:
+  documentation_uri: https://socketry.github.io/async-discord/
   source_code_uri: https://github.com/socketry/async-discord.git
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -101,8 +100,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Build Discord bots and use real time messaging.
 test_files: []