stoatrb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d34d4d67e82ebfa41c47ace5c40ed7e07cef241bc66c86da2eae9267840946c3
+  data.tar.gz: 6c7fad3f522ca70369b4d8f292caa6535de5613a509abd6d08986d04315ac23a
+SHA512:
+  metadata.gz: 7a11ed7db6ed626fe6f587ce08d29ad1f10ca0c69524d4ba335c54f273a89c4eea112bb84d3be81d69a282df9f3c716a7420c18242a0d0ac1933a6c9743cfc94
+  data.tar.gz: 1bd193a7980d36125fc1029fc3617cce06fb1ecd20ae303c9071fbbc39ece814dc183fdb2e86387825acdb84bc2d0fe359fe9a13fb0cbb43a6df3a8814da9023

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Roxanne Wolf
+
+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.

data/README.md

@@ -0,0 +1,95 @@
+# stoatrb
+
+Stoatrb is a Ruby package (a.k.a. Gem) that allows you to make stoat.chat bots and use stoat.chat webhooks using the Ruby programming language. This package (a.k.a. Gem) is not officially endorsed by stoat.chat amd this is not an official stoat.chat product.
+
+You need Ruby 3.0 or newer in order to use this package (Ruby 3.2 or newer is recommended)
+
+> [!NOTE]
+> This package (a.k.a. Gem) is in an alpha state so expect things to be buggy and/or broken.
+
+## ToDo
+
+This list contains a list of things that I know is broken and gotta fix. Contributing will be super helpful.
+
+- Fix reactions support
+
+## Setup
+
+You can install Revoltrb through the following methods:
+
+#### Method 1: Install from Gemfile
+
+Add the following to your Gemfile file and run the "[bundle install](https://rubygems.org/gems/stoatrb)" command:
+
+```ruby
+gem 'revoltrb'
+```
+
+or add the following to your Gemfile file.
+
+```ruby
+gem 'revoltrb', git: 'https://gitlab.com/roxannewolf/stoatrb'
+```
+
+#### Troubleshooting
+
+If you encounter the "Exited with code: 16 output:Ignoring debug-1.7.1 because its extensions are not built." error, most likely, there is something wrong with the parser package. This can be fixed by installing parser manually (gem install parser)
+
+## Usage
+
+You can make a simple bot like this:
+
+```ruby
+require 'stoatrb'
+
+bot = Stoatrb::StoatBot.new('REVOLT_BOT_TOKEN_HERE')
+
+bot.on_message do |message|
+	next if message['author'] == bot.user_id
+	content = message['content']&.downcase
+	channel_id = message['channel']
+
+	if content.include?("ping")
+		bot.send_message(channel_id, text: "Pong!")
+	end
+end
+
+bot.run
+```
+
+or you can make a bot with full prefix commands like this:
+
+```ruby
+require 'stoatrb'
+
+bot = Stoatrb::StoatBot.new('REVOLT_BOT_TOKEN_HERE', prefix: '!')
+
+bot.command(:ping) do |message, args|
+	channel_id = message['channel']
+	bot.send_message(channel_id, text: "Pong! You sent: #{args.join(' ')}")
+end
+
+bot.run
+```
+
+Webhook example:
+
+```ruby
+require 'stoatrb'
+# Webhook url should look like this: https://stoat.chat/api/webhooks/<WEBHOOK_ID>/<WEBHOOK_TOKEN>
+WEBHOOK_ID = ''
+WEBHOOK_TOKEN = ''
+webhook = StoatWebhooks::Webhook.new(WEBHOOK_ID, WEBHOOK_TOKEN)
+
+webhook.send_message(
+	content: "Stoatrb webhook message content",
+)
+```
+
+## Support and Help
+
+If you need help with this ruby package (a.k.a. Gem), feel free to join the [Roxanne Studios Stoat.chat Server](http://stt.gg/r4Ee2R1Z) and use the STOATRB category to talk about this package.
+
+## Contributing
+
+We are working to support more of Stoat.chat's API. Remember, the creator of this package is only a Ruby beginner so contributing to this project will mean a lot and can help with more coverage with the Stoat.chat API. Opening issues and Pull requests are welcome at our [Gitlab repo](https://gitlab.com/roxannewolf/stoatrb) and [Codeberg repo](https://codeberg.org/roxannewolf/stoatrb)

data/lib/stoatrb/bot.rb

@@ -0,0 +1,589 @@
+# lib/stoatrb/bot.rb
+require 'json'
+require 'net/http'
+require 'websocket-client-simple'
+require 'thread'
+require 'time'
+require_relative 'debuglogger'
+require_relative 'request_queue'
+require_relative 'webhooks'
+
+module Stoatrb
+	class StoatBot
+		EMOJI_MAP = {
+			':grinning:' => '😀',
+			':heart:' => '❤️',
+			':joy:' => '😂',
+			':unamused:' => '😒',
+			':sunglasses:' => '😎',
+			':thinking:' => '🤔',
+			':clap:' => '👏',
+			':thumbsup:' => '👍',
+			':thumbsdown:' => '👎',
+			':point_up:' => '☝️',
+			':+1:' => '👍',
+			':-1:' => '👎'
+		}.freeze
+
+		attr_reader :token, :user_id, :bot_name, :servers, :prefix, :bot_owner_id, :bot_discriminator, :bot_discoverable, :bot_creation_date, :webhooks
+		attr_accessor :websocket_url, :api_url, :cdn_url
+		# Initializes the bot with the provided token, API endpoints, and configuration.
+		def initialize(token, api_url: 'https://api.stoat.chat/0.8', websocket_url: 'wss://events.stoat.chat', cdn_url: 'https://cdn.stoatusercontent.com', prefix: nil, debuglogs: false, selfbot: false)
+			@token = token
+			@api_url = api_url
+			@websocket_url = websocket_url
+			@cdn_url = cdn_url
+
+			@user_id = nil
+			@bot_name = nil
+			@servers = {}
+			@commands = {}
+			@message_handlers = []
+
+			@websocket = nil
+			@websocket_thread = nil
+			@heartbeat_interval = 30 # Default heartbeat interval in seconds
+			@last_heartbeat_sent = Time.now.to_i
+			@running = false
+			@ready_event_received = false
+			@logger = Stoatrb::DebugLogger.new(debuglogs)
+			@request_queue = Stoatrb::RequestQueue.new(500)
+			@webhooks = Stoatrb::Webhooks.new(api_url, @logger, token, selfbot)
+
+			@prefix = "!"
+			@prefix = prefix if prefix
+			@selfbot = selfbot
+			@logger.debug "Stoat.chat Bot initialized. API: #{@api_url}, WS: #{@websocket_url}, CDN: #{@cdn_url}, Prefix: #{@prefix}"
+		end
+
+		def get_botinfo
+			{
+				'bot_id' => @user_id,
+				'bot_name' => @bot_name,
+				'bot_discriminator' => @bot_discriminator,
+				'bot_ownerid' => @bot_owner_id,
+				'bot_creationdate' => @bot_creation_date,
+				'bot_flags' => @bot_flags,
+				'bot_discoverable' => @bot_discoverable,
+				'bot_public' => @bot_public,
+				'bot_analytics' => @bot_analytics,
+				'bot_prefix' => @prefix,
+				'bot_token' => @token
+			}
+		end
+
+		# Log into the Stoat.chat bot
+		def login
+			@logger.debug "BOT: Bot attempting to start...."
+			# Step 1: Fetch initial bot user details via REST API using /users/@me with X-Bot-Token | As confirmed, /users/@me returns the bot's user object directly.
+			uri = URI("#{@api_url}/users/@me")
+			req = Net::HTTP::Get.new(uri)
+			_add_auth_header(req)
+			res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
+				http.request(req)
+			end
+
+			if res.is_a?(Net::HTTPSuccess)
+				bot_user_data = JSON.parse(res.body)
+				@logger.debug "Response Body (successful login attempt from /users/@me): #{res.body}"
+				@user_id = bot_user_data&.[]('_id')
+				@bot_name = bot_user_data&.[]('username')
+				@bot_discriminator = bot_user_data&.[]('discriminator')
+				bot_specific_info = bot_user_data&.[]('bot')
+				@bot_owner_id = bot_specific_info&.[]('owner')
+				@bot_flags = bot_specific_info&.[]('flags')
+				@bot_discoverable = nil
+				@bot_public = nil
+				@bot_analytics = nil
+				@bot_creation_date = Time.at(bot_user_data&.[]('created_at').to_i / 1000) rescue nil
+				if @user_id.nil? || @bot_name.nil?
+					@logger.debug "AN ERROR HAS OCCURED: Essential properties (_id, username) missing or nil in API response from /users/@me. Please inspect the 'Response Body' above for unexpected format."
+					return false
+				end
+
+				@logger.debug "Successfully identified as #{@bot_name} (ID: #{@user_id}) via REST API."
+				@logger.debug "Bot Owner ID: #{@bot_owner_id}, Owner ID: #{@bot_owner_id}, Discoverable: #{@bot_discoverable.inspect}, Created: #{@bot_creation_date}"
+			else
+				@logger.debug "AN ERROR HAS OCCURED: Initial REST API call failed.... #{res.message} (Code: #{res.code})"
+				@logger.debug "Please check your bot token. Cannot proceed with WebSocket connection. Response Body: #{res.body}"
+				return false
+			end
+			# Step 2: Connect to the WebSocket
+			@running = true
+			connect_websocket
+			@request_queue.start_processing
+			true
+		end
+		def run
+			begin
+				unless login
+					puts "Bot failed to log in. Exiting."
+					exit(1)
+				end
+				puts "Bot is online and running. Press Ctrl+C to stop."
+				@websocket_thread.join
+			rescue Interrupt
+				puts "\nCtrl+C detected. Shutting down bot gracefully..."
+			rescue => e
+				puts "An unhandled error occurred in the main script loop: #{e.message}"
+				puts e.backtrace.join("\n")
+			ensure
+				stop
+				puts "Bot process ended."
+			end
+		end
+
+		def set_presence(status)
+			valid_statuses = ['Online', 'Idle', 'Dnd', 'Focus', 'Invisible']
+			unless valid_statuses.include?(status)
+				@logger.debug "AN ERROR HAS OCCURED: Invalid status '#{status}'. Must be one of the following choices: #{valid_statuses.join(', ')}."
+				return false
+			end
+
+			@logger.debug "Attempting to set bot presence to '#{status}'."
+			uri = URI("#{@api_url}/users/@me")
+			req = Net::HTTP::Patch.new(uri)
+			_add_auth_header(req)
+			req['Content-Type'] = 'application/json'
+			payload = {
+				status: {
+					presence: status
+				}
+			}
+			req.body = payload.to_json
+			res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
+				http.request(req)
+			end
+
+			if res.is_a?(Net::HTTPSuccess)
+				@logger.debug "BOT: Presence has been changed to '#{status}'."
+				true
+			else
+				@logger.debug "AN ERROR HAS OCCURED: Failed to update presence. Response: #{res.message} (Code: #{res.code})"
+				@logger.debug "Response Body: #{res.body}"
+				false
+			end
+		rescue => e
+			@logger.debug "AN ERROR HAS OCCURED: Error setting presence: #{e.message}"
+			@logger.debug e.backtrace.join("\n")
+			false
+		end
+
+		def connect_websocket
+			if @websocket && @websocket.open? && @running
+				@logger.debug "WebSocket already open and running."
+				return
+			end
+
+			@logger.debug "Connecting to WebSocket: #{@websocket_url}"
+			ws_url_with_token = "#{@websocket_url}?token=#{@token}"
+			bot_instance = self
+			thread_logger = @logger
+
+			@websocket_thread = Thread.new do
+				begin
+					@websocket = WebSocket::Client::Simple.connect ws_url_with_token
+					@websocket.on :open do
+						thread_logger.debug "WebSocket connection opened!"
+					end
+					@websocket.on :message do |msg|
+						bot_instance.handle_websocket_message(msg.data)
+					end
+					@websocket.on :close do |e|
+						close_code = e&.code || 'N/A'
+						close_reason = e&.reason || 'No reason provided'
+						thread_logger.debug "WebSocket closed: #{close_code} - #{close_reason}."
+						bot_instance.instance_variable_set(:@websocket, nil)
+						if bot_instance.instance_variable_get(:@running)
+							thread_logger.debug "Attempting to reconnect in 5 seconds..."
+							sleep 5
+							bot_instance.connect_websocket
+						else
+							thread_logger.debug "BOT: Bot has stopped and will not try to reconnect" # Use local thread_logger
+						end
+					end
+					@websocket.on :error do |e|
+						error_message = e&.message || 'Unknown error'
+						thread_logger.debug "WebSocket error: #{error_message}"
+						@websocket.close if @websocket&.open?
+					end
+
+					while bot_instance.instance_variable_get(:@running)
+						if Time.now.to_i - @last_heartbeat_sent > @heartbeat_interval
+							bot_instance.send_heartbeat
+						end
+						sleep 1
+					end
+					thread_logger.debug "WebSocket thread loop finished."
+				rescue => e
+					thread_logger.debug "WebSocket thread unhandled exception: #{e.message}"
+					thread_logger.debug e.backtrace.join("\n")
+					bot_instance.instance_variable_set(:@websocket, nil)
+					if bot_instance.instance_variable_get(:@running)
+						thread_logger.debug "Attempting to reconnect in 5 seconds due to unhandled error..."
+						sleep 5
+						bot_instance.connect_websocket
+					else
+						thread_logger.debug "Bot is stopped, not attempting to reconnect after unhandled error."
+					end
+				end
+			end
+			sleep 1
+		end
+
+		def send_heartbeat
+			if @websocket && @websocket.open?
+				payload = { type: 'Ping', data: Time.now.to_i }
+				@websocket.send(payload.to_json)
+				@last_heartbeat_sent = Time.now.to_i
+			end
+		rescue OpenSSL::SSL::SSLError => e
+			@logger.debug "AN ERROR HAS OCCURED: Error sending heartbeat (SSL): #{e.message}"
+			@websocket&.close
+		rescue => e
+			@logger.debug "AN ERROR HAS OCCURED: Error sending heartbeat: #{e.message}"
+			@websocket&.close
+		end
+
+		def handle_websocket_message(raw_data)
+			begin
+				event = JSON.parse(raw_data)
+				event_type = event['type']
+				case event_type
+				when 'Ready'
+					@logger.debug "Received 'Ready' event. Populating initial data..."
+					if event['servers']
+						event['servers'].each do |server_data|
+							@servers[server_data['_id']] = {
+								'name' => server_data['name'],
+								'id' => server_data['_id']
+							}
+							@logger.debug "Stored server ID from Ready event: #{server_data['_id'].inspect}" # New debug
+						end
+						@logger.debug "Loaded #{event['servers'].count} real servers from 'Ready' event."
+					else
+						@logger.debug "'Ready' event received but no 'servers' array found."
+					end
+					@ready_event_received = true
+					@logger.debug "@ready_event_received set to true."
+				when 'Message'
+					unless event['author'] == @user_id
+						process_message(event)
+					end
+				when 'Authenticated'
+					@logger.debug "Successfully authenticated with WebSocket."
+				when 'Pong'
+					# @logger.debug "Received Pong response."
+				when 'Error'
+					@logger.debug "AN ERROR HAS OCCURED: Stoat.chat API Error received via WebSocket: #{event['error']}"
+				else
+					# @logger.debug "AN ERROR HAS OCCURED: Unhandled WebSocket event type: #{event_type}"
+				end
+			rescue JSON::ParserError => e
+				@logger.debug "AN ERROR HAS OCCURED: Failed to parse WebSocket message as JSON: #{e.message}"
+				@logger.debug "Raw message: #{raw_data}"
+			rescue => e
+				@logger.debug "AN ERROR HAS OCCURED: Error processing WebSocket message: #{e.message}"
+				@logger.debug e.backtrace.join("\n")
+			end
+		end
+
+		def on_message(&block)
+			@message_handlers << block
+		end
+		def command(command_name, required_permissions: [], nsfw_channel_required: false, &block)
+			cmd_key = command_name.to_s.downcase
+			@commands[cmd_key] = {
+				'block' => block,
+				'permissions' => required_permissions,
+				'nsfw_cmd' => nsfw_channel_required
+			}
+			@logger.debug "Command '#{command_name}' registered! Permissions: #{required_permissions.inspect}, NSFW required: #{nsfw_channel_required}."
+		end
+
+		def check_permissions(message, required_permissions, nsfw_channel_required)
+			@logger.debug "check_permissions called with required_permissions: #{required_permissions.inspect}, NSFW required: #{nsfw_channel_required}."
+			@logger.debug "message['channel'] value: #{message['channel'].inspect}"
+
+			server_id_from_message = message['member']&.[]('_id')&.[]('server')
+			@logger.debug "message['member']['_id']['server'] value: #{server_id_from_message.inspect}"
+
+			if required_permissions.empty? && !nsfw_channel_required
+				@logger.debug "Permission Check: No specific permissions or NSFW requirement. Allowing command."
+				return true
+			end
+			user_id = message['author']
+
+			# --- Permission Check ---
+			@logger.debug "PERMISSION DEBUG: User ID from message (user_id): '#{user_id}' | Bot Owner ID stored (@bot_owner_id): '#{@bot_owner_id}'"
+			@logger.debug "Are they equal? (user_id == @bot_owner_id): #{user_id == @bot_owner_id}"
+			# @logger.debug "User ID char codes: #{user_id.each_char.map(&:ord).join(', ')}"
+			# @logger.debug "Bot Owner ID char codes: #{@bot_owner_id.each_char.map(&:ord).join(', ')}"
+			# --- BotOwner Check ---
+			if required_permissions.include?('BotOwner')
+				if user_id == @bot_owner_id
+					@logger.debug "Permission Check: User is the bot owner. Allowing command."
+					return true
+				else
+					@logger.debug "Permission Check: User is NOT the bot owner. Denying command."
+					return false
+				end
+			end
+			# --- NSFW Channel Check ---
+			channel_id = message['channel']
+			if server_id_from_message.nil?
+				if nsfw_channel_required
+					@logger.debug "Permission Check: Command requires NSFW channel, but message is in DM. Denying command."
+					return false
+				end
+			else
+				channel_details = get_channel_details(channel_id)
+				if channel_details.nil?
+					@logger.debug "Permission Check: Command requires NSFW channel but could not retrieve channel details. Denying command."
+					return false
+				end
+				is_channel_nsfw = channel_details['nsfw'] || false
+				if nsfw_channel_required && !is_channel_nsfw
+					@logger.debug "Permission Check: Command requires NSFW channel, but current channel is NOT NSFW marked. Denying."
+					return false
+				elsif !nsfw_channel_required && is_channel_nsfw
+					@logger.debug "Permission Check: Command does not require NSFW channel, but is in NSFW marked channel. Allowing."
+				end
+			end
+
+			if !required_permissions.empty?
+				@logger.debug "User #{user_id} is not the bot owner. Requires permissions: #{required_permissions.inspect}. (Full permission check for non-owner, server-specific permissions not implemented)."
+				return false
+			end
+			@logger.debug "Permission Check: All checks passed. Allowing command."
+			true
+		end
+
+		def process_message(message)
+			unless @ready_event_received
+				@logger.debug "AN ERROR HAS OCCURED: Bot is not ready for commands"
+				return
+			end
+
+			unless @selfbot
+				return if message['author'] == @user_id
+			end
+
+			content = message['content']&.strip
+			return if content.nil? || content.empty?
+			@logger.debug "Full Message object received in process_message: #{message.inspect}"
+
+			@commands.each do |cmd_name, cmd_data|
+				command_full_string = "#{@prefix}#{cmd_name}"
+				if content.downcase.start_with?(command_full_string.downcase)
+					args_string = content[command_full_string.length..]&.strip
+					args = args_string.to_s.split(/\s+/)
+					args = [] if args == ['']
+					# --- Permission Check (Pass both permissions and nsfw_channel_required to check_permissions) ---
+					if check_permissions(message, cmd_data['permissions'], cmd_data['nsfw_cmd'])
+						@logger.debug "Executing command: '#{cmd_name}' with args: #{args.inspect}"
+						cmd_data['block'].call(message, args)
+					else
+						channel_id = message['channel']
+						if cmd_data['nsfw_cmd'] && message['member']
+							channel_details = get_channel_details(channel_id)
+							if channel_details && !channel_details['nsfw']
+								self.send_message(channel_id, text: "⛔ A NSFW marked channel is required to use the following command: `#{cmd_name}`")
+							else
+								self.send_message(channel_id, text: "⛔ You don't have permission to use the `#{cmd_name}` command.")
+							end
+						else
+							self.send_message(channel_id, text: "⛔ You don't have permission to use the `#{cmd_name}` command.")
+						end
+					end
+					return
+				end
+			end
+
+			@message_handlers.each do |handler|
+				@logger.debug "Calling general message handler for: '#{content}'"
+				handler.call(message)
+			end
+		end
+
+		def send_message(channel_id, text: nil, embeds: nil, masquerade_name: nil, masquerade_avatar_url: nil)
+			if text.nil? && (embeds.nil? || embeds.empty?)
+				@logger.debug "AN ERROR HAS OCCURED: Cannot send empty message or embeds."
+				return
+			end
+
+			payload = {}
+			payload[:content] = text if text
+			
+			if embeds && !embeds.empty?
+				filtered_embeds = embeds.map do |embed|
+					supported_keys = ['title', 'description', 'colour', 'url', 'icon_url', 'media']
+					embed.select { |k, v| supported_keys.include?(k.to_s) }
+				end
+				payload[:embeds] = filtered_embeds
+			end
+			if masquerade_name || masquerade_avatar_url
+				payload[:masquerade] = {}
+				payload[:masquerade][:name] = masquerade_name if masquerade_name
+				payload[:masquerade][:avatar] = masquerade_avatar_url if masquerade_avatar_url
+			end
+
+			@request_queue.enqueue do
+				@logger.debug "Attempting to send message to channel '#{channel_id}' via queue..."
+				uri = URI("#{@api_url}/channels/#{channel_id}/messages")
+				req = Net::HTTP::Post.new(uri)
+				_add_auth_header(req)
+				req['Content-Type'] = 'application/json'
+				req.body = payload.to_json
+
+				res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
+					http.request(req)
+				end
+
+				if res.is_a?(Net::HTTPSuccess)
+					@logger.debug "Message sent successfully!"
+				else
+					@logger.debug "AN ERROR HAS OCCURED: Failed to send message: #{res.message} (Code: #{res.code})"
+					@logger.debug "Response Body: #{res.body}"
+				end
+			end
+		rescue => e
+			@logger.debug "AN ERROR HAS OCCURED: Error enqueuing message: #{e.message}"
+			@logger.debug e.backtrace.join("\n")
+		end
+
+		def find_unicode_emoji(shortcode)
+			EMOJI_MAP[shortcode]
+		end
+
+		def add_reaction(channel_id, message_id, emoji_id)
+			if emoji_id.start_with?(':') && emoji_id.end_with?(':')
+				@logger.debug "AN ERROR HAS OCCURED: Cannot add reaction with shortcode '#{emoji_id}'. Please use the actual Unicode emoji or a custom emoji ID."
+				return
+			end
+
+			@request_queue.enqueue do
+				@logger.debug "Attempting to add reaction '#{emoji_id}' to message '#{message_id}' in channel '#{channel_id}' via queue."
+				encoded_emoji_id = CGI.escape(emoji_id)
+
+				uri = URI("#{@api_url}/channels/#{channel_id}/messages/#{message_id}/reactions/#{encoded_emoji_id}")
+				req = Net::HTTP::Put.new(uri)
+				_add_auth_header(req)
+
+				res = nil
+				begin
+					res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https', read_timeout: 10, open_timeout: 10) do |http|
+						http.request(req)
+					end
+				rescue Net::ReadTimeout => e
+					@logger.debug "AN ERROR HAS OCCURED: The network request timed out while waiting for a response after 10 seconds. Error: #{e.message}"
+					return
+				rescue Net::OpenTimeout => e
+					@logger.debug "AN ERROR HAS OCCURED: The network request timed out while trying to open a connection after 10 seconds. Error: #{e.message}"
+					return
+				rescue => e
+					@logger.debug "AN ERROR HAS OCCURED: An unexpected error occurred during the network request. Error: #{e.message}"
+					return
+				ensure
+					@logger.debug "Network request to add reaction finished."
+				end
+
+				@logger.debug "Received response with code: #{res.code}"
+				if res.is_a?(Net::HTTPSuccess) || res.code == '204'
+					@logger.debug "Reaction added successfully!"
+				else
+					@logger.debug "AN ERROR HAS OCCURED: Failed to add reaction: #{res.message} (Code: #{res.code})"
+					@logger.debug "Response Body: #{res.body}"
+					if res.code == '403'
+						@logger.debug "HINT: The bot may be missing the 'AddReactions' permission in this channel or server."
+					end
+				end
+			end
+		end
+
+		def remove_reaction(channel_id, message_id, emoji_id, user_id: nil)
+			target_user_id = user_id || @user_id
+			@request_queue.enqueue do
+				@logger.debug "Attempting to remove reaction '#{emoji_id}' from message '#{message_id}' by user '#{target_user_id}' in channel '#{channel_id}' via queue."
+
+				encoded_emoji_id = CGI.escape(emoji_id)
+
+				uri = URI("#{@api_url}/channels/#{channel_id}/messages/#{message_id}/reactions/#{encoded_emoji_id}?user_id=#{target_user_id}")
+				req = Net::HTTP::Delete.new(uri)
+				_add_auth_header(req)
+				res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
+					http.request(req)
+				end
+				if res.is_a?(Net::HTTPSuccess) || res.code == '204'
+					@logger.debug "Reaction removed successfully!"
+				else
+					@logger.debug "AN ERROR HAS OCCURED: Failed to remove reaction: #{res.message} (Code: #{res.code})"
+					@logger.debug "Response Body: #{res.body}"
+				end
+			end
+		rescue => e
+			@logger.debug "AN ERROR HAS OCCURED: Error enqueuing remove reaction: #{e.message}"
+			@logger.debug e.backtrace.join("\n")
+		end
+
+		def get_channel_details(channel_id)
+			@logger.debug "Fetching channel details for ID: #{channel_id} (direct API call for permission check)."
+			uri = URI("#{@api_url}/channels/#{channel_id}")
+			req = Net::HTTP::Get.new(uri)
+			req['x-bot-token'] = @token
+
+			res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
+				http.request(req)
+			end
+
+			if res.is_a?(Net::HTTPSuccess)
+				JSON.parse(res.body)
+			else
+				@logger.debug "AN ERROR HAS OCCURED: Failed to fetch channel details for #{channel_id}: #{res.message} (Code: #{res.code})"
+				nil
+			end
+		rescue => e
+			@logger.debug "AN ERROR HAS OCCURED: Error fetching channel details: #{e.message}"
+			nil
+		end
+
+		def get_server_info(server_id)
+			@logger.debug "get_server_info called with server_id: '#{server_id}' (Type: #{server_id.class}, Length: #{server_id.length})"
+			@logger.debug "Available server IDs in cache (@servers.keys): #{@servers.keys.inspect}"
+			found_server = @servers[server_id]
+			@logger.debug "Result of @servers[server_id]: #{found_server.inspect}"
+			found_server
+		end
+		def get_server_name(server_id)
+			@servers[server_id]&.[]('name')
+		end
+
+		def stop
+			@logger.debug "Stopping bot..."
+			@running = false
+			if @websocket_thread && @websocket_thread.alive?
+				unless @websocket_thread.join(5)
+					@logger.debug "WebSocket thread did not terminate gracefully, forcing kill."
+					@websocket_thread.kill
+				end
+				@logger.debug "WebSocket thread terminated."
+			end
+			if @websocket && @websocket.open?
+				@websocket.close
+				@logger.debug "WebSocket closed."
+			end
+			@request_queue.stop_processing
+			@logger.debug "Bot stopped."
+		end
+
+		private
+
+		def _add_auth_header(request)
+			if @selfbot
+				request['x-session-token'] = @token
+			else
+				request['x-bot-token'] = @token
+			end
+		end
+	end
+end

data/lib/stoatrb/debuglogger.rb

@@ -0,0 +1,13 @@
+# lib/stoatrb/debuglogger.rb
+
+module Stoatrb
+	class DebugLogger
+		def initialize(enabled = false)
+			@enabled = enabled
+		end
+
+		def debug(message)
+			puts message if @enabled
+		end
+	end
+end

data/lib/stoatrb/request_queue.rb

@@ -0,0 +1,59 @@
+# lib/stoatrb/request_queue.rb
+
+require 'thread'
+
+module Stoatrb
+	class RequestQueue
+		def initialize(delay_between_requests_ms = 100)
+			@queue = []
+			@mutex = Mutex.new
+			@condition = ConditionVariable.new
+			@processing_thread = nil
+			@running = false
+			@delay_between_requests = delay_between_requests_ms / 1000.0
+			@logger = Stoatrb::DebugLogger.new
+		end
+
+		def enqueue(&block)
+			@mutex.synchronize do
+				@queue << block
+				@condition.signal
+			end
+		end
+
+		def start_processing
+			return if @running
+
+			@running = true
+			@processing_thread = Thread.new do
+				@logger.debug "RequestQueue processing thread started."
+				while @running
+					request = nil
+					@mutex.synchronize do
+						@condition.wait(@mutex) if @queue.empty?
+						request = @queue.shift unless @queue.empty?
+					end
+
+					if request
+						begin
+							request.call
+							sleep @delay_between_requests
+						rescue => e
+							@logger.debug "AN ERROR HAS OCCURED: Error processing queued request: #{e.message}"
+							@logger.debug e.backtrace.join("\n")
+						end
+					end
+				end
+				@logger.debug "RequestQueue processing thread stopped."
+			end
+		end
+
+		def stop_processing
+			@running = false
+			@mutex.synchronize do
+				@condition.signal
+			end
+			@processing_thread.join if @processing_thread&.alive?
+		end
+	end
+end

data/lib/stoatrb/version.rb

@@ -0,0 +1,6 @@
+# lib/stoatrb/version.rb
+
+module Stoatrb
+	# The current version of stoatrb
+	VERSION = "0.1.0"
+end

data/lib/stoatrb/webhooks.rb

@@ -0,0 +1,104 @@
+# lib/stoatrb/webhooks.rb
+require 'json'
+require 'net/http'
+require 'uri'
+
+module Stoatrb
+	class Webhooks
+		attr_reader :api_url, :logger, :token, :selfbot
+		def initialize(api_url, logger, token, selfbot)
+			@api_url = api_url
+			@logger = logger
+			@token = token
+			@selfbot = selfbot
+		end
+
+		def create_webhook(channel_id, name, avatar_url: nil)
+			@logger.debug "Attempting to create a webhook for channel '#{channel_id}' with name '#{name}'."
+
+			uri = URI("#{@api_url}/channels/#{channel_id}/webhooks")
+			req = Net::HTTP::Post.new(uri)
+			if @selfbot
+				req['Authorization'] = @token
+			else
+				req['x-bot-token'] = @token
+			end
+			req['Content-Type'] = 'application/json'
+
+			payload = {
+				name: name
+			}
+			payload[:avatar] = avatar_url unless avatar_url.nil?
+			req.body = payload.to_json
+
+			res = nil
+			begin
+				res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https', read_timeout: 10, open_timeout: 10) do |http|
+					http.request(req)
+				end
+			rescue Net::ReadTimeout => e
+				@logger.debug "AN ERROR HAS OCCURED: Network request timed out while reading: #{e.message}"
+				return nil
+			rescue Net::OpenTimeout => e
+				@logger.debug "AN ERROR HAS OCCURED: Network request timed out while connecting: #{e.message}"
+				return nil
+			rescue => e
+				@logger.debug "AN ERROR HAS OCCURED: An unexpected error occurred while creating the webhook: #{e.message}"
+				return nil
+			end
+
+			if res.is_a?(Net::HTTPSuccess)
+				webhook_data = JSON.parse(res.body)
+				@logger.debug "Webhook created successfully! Details: #{res.body}"
+				@logger.debug "Webhook Name: #{webhook_data['name']} | Webhook ID: #{webhook_data['id']}"
+				@logger.debug "Webhook Channel ID: #{webhook_data['channel_id']}"
+				return webhook_data
+			else
+				@logger.debug "AN ERROR HAS OCCURED: Failed to create webhook. (Code: #{res.code}) Response: #{res.message}"
+				@logger.debug "Response Body: #{res.body}"
+				return nil
+			end
+		end
+	end
+end
+
+module StoatWebhooks
+	class Webhook
+		DEFAULT_API_URL = 'https://stoat.chat/api'.freeze
+		def initialize(webhook_id, webhook_token, api_url: DEFAULT_API_URL)
+			@webhook_id = webhook_id
+			@webhook_token = webhook_token
+			@api_url = api_url
+			@uri = URI("#{@api_url}/webhooks/#{@webhook_id}/#{@webhook_token}")
+		end
+
+		def send_message(content:, embeds: nil)
+			payload = {
+				content: content
+			}
+
+			if embeds
+				payload[:embeds] = Array(embeds)
+			end
+
+			http = Net::HTTP.new(@uri.host, @uri.port)
+			http.use_ssl = true
+			request = Net::HTTP::Post.new(@uri.path, 'Content-Type' => 'application/json')
+			request.body = payload.to_json
+
+			begin
+				response = http.request(request)
+				if response.code.to_i == 204 || response.code.to_i == 200
+					return true
+				else
+					puts "[Stoatrb Webhooks] AN ERROR HAS OCCURED: Status code: #{response.code}"
+					puts "[Stoatrb Webhooks] Response body: #{response.body}"
+					return false
+				end
+			rescue StandardError => e
+				puts "[Stoatrb Webhooks] AN ERROR HAS OCCURED: #{e.message}"
+				return false
+			end
+		end
+	end
+end

data/lib/stoatrb.rb

@@ -0,0 +1,14 @@
+# lib/stoatrb.rb
+require_relative 'stoatrb/bot'
+require_relative 'stoatrb/version'
+require_relative 'stoatrb/debuglogger'
+require_relative 'stoatrb/request_queue'
+require_relative 'stoatrb/webhooks'
+
+module Stoatrb
+	# This module can serve as a namespace for the gem's classes. For now, it's a direct require.
+end
+
+module StoatWebhooks
+	# This module can serve as a namespace for the gem's classes. For now, it's a direct require.
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: stoatrb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Roxanne Studios
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.13.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.13.2
+- !ruby/object:Gem::Dependency
+  name: net-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+- !ruby/object:Gem::Dependency
+  name: websocket-client-simple
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.0
+- !ruby/object:Gem::Dependency
+  name: thread
+  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'
+- !ruby/object:Gem::Dependency
+  name: parser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.3.9.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.3.9.0
+description: The first Ruby package (a.k.a. gem) to exist for making Stoat.chat bots
+  and using Stoat.chat webhooks. This project is not officially endorsed by stoat.chat
+email:
+- ''
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/stoatrb.rb
+- lib/stoatrb/bot.rb
+- lib/stoatrb/debuglogger.rb
+- lib/stoatrb/request_queue.rb
+- lib/stoatrb/version.rb
+- lib/stoatrb/webhooks.rb
+homepage: https://gitlab.com/roxannewolf/stoatrb
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby gem for making stoat.chat bots
+test_files: []