onyxcord 3.2.8 → 4.0.0.beta.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 519bb339e62e93fa61c6a48e004937ad6e7b7e3645abc6be14709edafb4c05cc
-  data.tar.gz: efb25e85bdd412727c3f46a69c1b92ebe02a557cb67e878e9040616a25abfa02
+  metadata.gz: 4fac344c79bce79ade61b9d7e1d40a756581380e31945ffb93470b5df4ced0c8
+  data.tar.gz: c74bbc605deb09a8e19d2a904a4b10e11b27b2a1909403113a2c589ff04de3fc
 SHA512:
-  metadata.gz: 4313a469aa21679b5b6522f954a25a16e9ef07071a31b09c61fdd5a23fe9dc3bd9c8965a0bab94ae758450140501d619acb107ebb31ac4e7f98779745afa37c9
-  data.tar.gz: f1accfb656c81f934c96b46af5521c222bc7995eed2445377ef2acf4c868e1ebbcc6840b814b395b0476f0f27d66643c9687899d61ad06c2bbee89c22a8d117a
+  metadata.gz: d28b1b62c8e2b5bba98094e9f43d25feb77afbe9b004f3c642be4efe2cd03e487ce0a42d14e413bc840c62aee9ebced716107ef01f01eea530900acfa66d2508
+  data.tar.gz: db0532185853f82710423f20df5b1136f22c8d325782da62642c0855a0398e5585aa15ecc8ab34fd1ad7d7d2a88555c588b7468735b088d73b36c748462c8f56

data/lib/onyxcord/application_commands.rb

@@ -3,6 +3,8 @@
 require 'onyxcord/interactions'
 
 module OnyxCord
+  # @see OnyxCord::Interactions
+  # @deprecated Use {OnyxCord::Interactions} directly.
   module ApplicationCommands
     Command = Interactions::Command
     Option = Interactions::Option

data/lib/onyxcord/bot.rb

@@ -9,6 +9,8 @@ require_relative 'core/bot/oauth'
 require_relative 'core/bot/presence'
 require_relative 'core/bot/awaits'
 require_relative 'core/bot/application_commands'
+require_relative 'cogs/bot'
+require_relative 'cogs/extensions'
 
 module OnyxCord
   # Represents a Discord bot, including servers, users, etc.
@@ -59,6 +61,8 @@ module OnyxCord
     include Presence
     include Awaits
     include ApplicationCommands
+    include Cogs
+    include Extensions
 
     # Makes a new bot with the given authentication data. It will be ready to be added event handlers to and can
     # eventually be run with {#run}.
@@ -117,7 +121,8 @@ module OnyxCord
       executor_queue_size = config.normalize_event_queue_size(event_queue_size)
 
       LOGGER.mode = log_mode
-      LOGGER.token = token if redact_token
+      @redact_token = redact_token
+      LOGGER.token = token if @redact_token
 
       @should_parse_self = parse_self
 
@@ -168,6 +173,7 @@ module OnyxCord
 
       @application_commands = {}
       @request_members_rl = {}
+      @cogs = {}
     end
 
     # The list of users the bot shares a server with.
@@ -225,7 +231,7 @@ module OnyxCord
     # @return [GlobalEmoji, nil] the emoji identified by the name, or `nil` if it couldn't be found.
     def find_emoji(name)
       LOGGER.out("Resolving emoji #{name}")
-      emoji.find { |element| element.name == name }
+      emoji.values.find { |element| element.name == name }
     end
 
     # The bot's user profile. This special user object can be used
@@ -235,7 +241,7 @@ module OnyxCord
       return @profile if @profile
 
       response = OnyxCord::REST::User.profile(@token)
-      @profile = Profile.new(JSON.parse(response), self)
+      @profile = Profile.new(OnyxCord::Internal::JSON.parse(response), self)
     end
 
     alias_method :bot_user, :profile
@@ -244,7 +250,7 @@ module OnyxCord
     # @return [Application] The bot's application info.
     def bot_application
       response = REST.oauth_application(token)
-      Application.new(JSON.parse(response), self)
+      Application.new(OnyxCord::Internal::JSON.parse(response), self)
     end
 
     alias_method :bot_app, :bot_application
@@ -253,8 +259,8 @@ module OnyxCord
     # Get the role connection metadata records associated with this application.
     # @return [Array<RoleConnectionMetadata>] the role connection metadata records associated with this application.
     def role_connection_metadata_records
-      response = REST::Application.get_application_role_connection_metadata_records(@bot.token, @id)
-      JSON.parse(response).map { |role_connection| RoleConnectionMetadata.new(role_connection, @bot) }
+      response = REST::Application.get_application_role_connection_metadata_records(token, @client_id)
+      OnyxCord::Internal::JSON.parse(response).map { |role_connection| RoleConnectionMetadata.new(role_connection, self) }
     end
 
     # The Discord API token received when logging in. Useful to explicitly call

data/lib/onyxcord/cache/manager.rb

@@ -26,7 +26,7 @@ module OnyxCord
 
     # Initializes this cache
     def init_cache
-      @cache_policy ||= OnyxCord.configuration.normalize_cache(:full)
+      @cache_policy ||= OnyxCord.configuration.normalize_cache(OnyxCord.configuration.cache)
       sizes = OnyxCord.configuration.cache_sizes
 
       @users = cache_enabled?(:users) ? LruRedux::ThreadSafeCache.new(sizes.users) : nil
@@ -73,7 +73,7 @@ module OnyxCord
     def fetch_voice_regions
       regions_by_id = {}
 
-      regions = JSON.parse REST.voice_regions(token)
+      regions = OnyxCord::Internal::JSON.parse REST.voice_regions(token)
       regions.each do |data|
         regions_by_id[data['id']] = VoiceRegion.new(data)
       end
@@ -99,7 +99,7 @@ module OnyxCord
       rescue OnyxCord::Errors::UnknownChannel
         return nil
       end
-      channel = Channel.new(JSON.parse(response), self, server)
+      channel = Channel.new(OnyxCord::Internal::JSON.parse(response), self, server)
       @channels[id] = channel if cache_enabled?(:channels)
       channel
     end
@@ -120,7 +120,7 @@ module OnyxCord
       rescue OnyxCord::Errors::UnknownUser
         return nil
       end
-      user = User.new(JSON.parse(response), self)
+      user = User.new(OnyxCord::Internal::JSON.parse(response), self)
       @users[id] = user if cache_enabled?(:users)
       user
     end
@@ -139,7 +139,7 @@ module OnyxCord
       rescue OnyxCord::Errors::NoPermission
         return nil
       end
-      server = Server.new(JSON.parse(response), self)
+      server = Server.new(OnyxCord::Internal::JSON.parse(response), self)
       @servers[id] = server if cache_enabled?(:servers)
       server
     end
@@ -161,7 +161,7 @@ module OnyxCord
       rescue OnyxCord::Errors::UnknownUser, OnyxCord::Errors::UnknownMember
         return nil
       end
-      member = Member.new(JSON.parse(response), server, self)
+      member = Member.new(OnyxCord::Internal::JSON.parse(response), server, self)
       server.cache_member(member)
     end
 
@@ -176,7 +176,7 @@ module OnyxCord
 
       debug("Creating pm channel with user id #{id}")
       response = REST::User.create_pm(token, id)
-      channel = Channel.new(JSON.parse(response), self)
+      channel = Channel.new(OnyxCord::Internal::JSON.parse(response), self)
       @pm_channels[id] = channel if cache_enabled?(:pm_channels)
       channel
     end
@@ -190,7 +190,7 @@ module OnyxCord
       id = id.resolve_id
       return @server_previews[id] if @server_previews&.[](id)
 
-      response = JSON.parse(REST::Server.preview(token, id))
+      response = OnyxCord::Internal::JSON.parse(REST::Server.preview(token, id))
       preview = ServerPreview.new(response, self)
       @server_previews[id] = preview if cache_enabled?(:server_previews)
       preview
@@ -301,7 +301,7 @@ module OnyxCord
     # @return [Invite] The invite with information about the given invite URL.
     def invite(invite)
       code = resolve_invite_code(invite)
-      Invite.new(JSON.parse(REST::Invite.resolve(token, code)), self)
+      Invite.new(OnyxCord::Internal::JSON.parse(REST::Invite.resolve(token, code)), self)
     end
 
     # Finds a channel given its name and optionally the name of the server it is in.

data/lib/onyxcord/cogs/bot.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module OnyxCord
+  class Bot
+    module Cogs
+      attr_reader :cogs
+
+      def add_cog(cog)
+        @cogs ||= {}
+        raise ArgumentError, "Cog #{cog.qualified_name} is already loaded" if @cogs.key?(cog.qualified_name)
+
+        cog._inject(self)
+        @cogs[cog.qualified_name] = cog
+      end
+
+      def remove_cog(name)
+        @cogs ||= {}
+        cog = @cogs.delete(name.to_s)
+        cog&._eject(self)
+      end
+
+      def get_cog(name)
+        @cogs ||= {}
+        @cogs[name.to_s]
+      end
+    end
+  end
+end

data/lib/onyxcord/cogs/cog.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+module OnyxCord; end
+
+require 'onyxcord/commands/container'
+require 'onyxcord/cogs/cog_meta'
+
+module OnyxCord
+  class Cog
+    include CogMeta
+
+    attr_reader :bot, :commands, :application_commands
+
+    def self.inherited(child)
+      child.include CogMeta
+      super
+    end
+
+    def initialize(bot)
+      @bot = bot
+      _update_copy
+    end
+
+    def cog_load; end
+
+    def cog_unload; end
+
+    def cog_command_error(_event, _error); end
+
+    def cog_slash_command_error(_context, _error); end
+
+    def cog_user_command_error(_context, _error); end
+
+    def cog_message_command_error(_context, _error); end
+
+    def cog_check(_event)
+      true
+    end
+
+    def cog_slash_command_check(_context)
+      true
+    end
+
+    def cog_user_command_check(_context)
+      true
+    end
+
+    def cog_message_command_check(_context)
+      true
+    end
+
+    def cog_before_invoke(_event); end
+
+    def cog_after_invoke(_event, _result); end
+
+    def cog_slash_before_invoke(_context); end
+
+    def cog_slash_after_invoke(_context, _result); end
+
+    def cog_user_before_invoke(_context); end
+
+    def cog_user_after_invoke(_context, _result); end
+
+    def cog_message_before_invoke(_context); end
+
+    def cog_message_after_invoke(_context, _result); end
+
+    def _inject(bot)
+      @bot = bot
+      old_commands = (bot.instance_variable_get(:@commands) || {}).dup
+      old_application_commands = (bot.application_command_registry.commands || {}).dup
+      old_application_handlers = (bot.instance_variable_get(:@application_commands) || {}).dup
+      old_event_handlers = clone_event_handlers(bot.instance_variable_get(:@event_handlers))
+      old_raw_handlers = (bot.instance_variable_get(:@raw_handlers) || []).dup
+
+      inject_commands(bot)
+      inject_listeners(bot)
+      cog_load
+      self
+    rescue StandardError
+      bot.instance_variable_set(:@commands, old_commands)
+      bot.application_command_registry.commands.replace(old_application_commands)
+      bot.instance_variable_set(:@application_commands, old_application_handlers)
+      bot.instance_variable_set(:@event_handlers, old_event_handlers)
+      bot.instance_variable_set(:@raw_handlers, old_raw_handlers)
+      raise
+    end
+
+    def _eject(bot)
+      eject_commands(bot)
+      eject_listeners(bot)
+      cog_unload
+      self
+    end
+
+    def _update_copy
+      @commands = copy_prefix_commands
+      @application_commands = self.class.application_commands.transform_values do |command|
+        copy = command.copy_for(self)
+        copy.parse(&copy.block) if copy.block && copy.options.empty?
+        copy
+      end
+      @listeners = self.class.listeners.map { |listener| listener.merge(names: listener[:names].dup) }
+    end
+
+    # rubocop:disable Naming/AccessorMethodName
+    def get_commands
+      @commands.values.grep(Commands::Command)
+    end
+
+    def get_application_commands
+      @application_commands.values
+    end
+
+    def get_listeners
+      @listeners
+    end
+    # rubocop:enable Naming/AccessorMethodName
+
+    def walk_commands
+      get_commands + get_application_commands.flat_map { |command| [command, *walk_options(command.options)] }
+    end
+
+    def handled_cog_command_error?(event, error)
+      return false unless overrides?(:cog_command_error)
+
+      cog_command_error(event, error)
+      true
+    end
+
+    def handled_cog_application_command_error?(context, error, command)
+      method_name = case command.type
+                    when :chat_input, :primary_entry_point then :cog_slash_command_error
+                    when :user then :cog_user_command_error
+                    when :message then :cog_message_command_error
+                    end
+      return false unless method_name && overrides?(method_name)
+
+      public_send(method_name, context, error)
+      true
+    end
+
+    def passed_cog_command_check?(event)
+      return true unless overrides?(:cog_check)
+
+      cog_check(event)
+    end
+
+    def passed_cog_application_command_check?(context, command)
+      method_name = case command.type
+                    when :chat_input, :primary_entry_point then :cog_slash_command_check
+                    when :user then :cog_user_command_check
+                    when :message then :cog_message_command_check
+                    end
+      return true unless method_name && overrides?(method_name)
+
+      public_send(method_name, context)
+    end
+
+    def invoke_cog_before_invoke(event)
+      return unless overrides?(:cog_before_invoke)
+
+      cog_before_invoke(event)
+    end
+
+    def invoke_cog_after_invoke(event, result)
+      return unless overrides?(:cog_after_invoke)
+
+      cog_after_invoke(event, result)
+    end
+
+    def invoke_cog_application_before_invoke(context, command)
+      method_name = case command.type
+                    when :chat_input, :primary_entry_point then :cog_slash_before_invoke
+                    when :user then :cog_user_before_invoke
+                    when :message then :cog_message_before_invoke
+                    end
+      return unless method_name && overrides?(method_name)
+
+      public_send(method_name, context)
+    end
+
+    def invoke_cog_application_after_invoke(context, result, command)
+      method_name = case command.type
+                    when :chat_input, :primary_entry_point then :cog_slash_after_invoke
+                    when :user then :cog_user_after_invoke
+                    when :message then :cog_message_after_invoke
+                    end
+      return unless method_name && overrides?(method_name)
+
+      public_send(method_name, context, result)
+    end
+
+    private
+
+    def overrides?(method_name)
+      method(method_name).owner != OnyxCord::Cog
+    end
+
+    def copy_prefix_commands
+      copied = {}
+
+      (self.class.commands || {}).each_value do |command|
+        next unless command.is_a?(Commands::Command)
+
+        copy = command.copy_for(self)
+        copied[copy.name] = copy
+        copy.attributes[:aliases].each { |name| copied[name] = Commands::CommandAlias.new(name, copy) }
+      end
+
+      copied
+    end
+
+    def walk_options(options)
+      options.flat_map { |option| [option, *walk_options(option.options)] }
+    end
+
+    def inject_commands(bot)
+      @__onyxcord_injected_commands = @commands.keys
+      bot_commands = bot.instance_variable_get(:@commands) || {}
+      bot.instance_variable_set(:@commands, bot_commands.merge(@commands))
+
+      @__onyxcord_injected_application_commands = @application_commands.keys
+      @application_commands.each_value { |command| bot.application_command_registry.register(command) }
+    end
+
+    def inject_listeners(bot)
+      @__onyxcord_injected_listeners = []
+      @listeners.each do |listener|
+        listener[:names].each do |name|
+          raise ArgumentError, "Unknown listener event #{name}" unless bot.respond_to?(name)
+
+          handler = bot.public_send(name, listener[:attributes]) { |event| instance_exec(event, &listener[:block]) }
+          @__onyxcord_injected_listeners << handler
+        end
+      end
+    end
+
+    def eject_commands(bot)
+      bot_commands = bot.instance_variable_get(:@commands)
+      @__onyxcord_injected_commands&.each do |name|
+        bot_commands&.delete(name) if bot_commands[name].equal?(@commands[name])
+      end
+
+      registry_commands = bot.application_command_registry.commands
+      application_handlers = bot.instance_variable_get(:@application_commands)
+      @__onyxcord_injected_application_commands&.each do |name|
+        registry_commands.delete(name) if registry_commands[name].equal?(@application_commands[name])
+        application_handlers&.delete(name.to_sym)
+      end
+    end
+
+    def eject_listeners(bot)
+      @__onyxcord_injected_listeners&.each { |handler| bot.remove_handler(handler) }
+      @__onyxcord_injected_listeners = []
+    end
+
+    def clone_event_handlers(handlers)
+      return {} unless handlers
+
+      handlers.transform_values(&:dup)
+    end
+  end
+end

data/lib/onyxcord/cogs/cog_meta.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module OnyxCord
+  module CogMeta
+    def self.included(base)
+      base.extend Commands::CommandContainer
+      base.extend ClassMethods
+    end
+
+    def qualified_name
+      self.class.name || self.class.to_s
+    end
+
+    def description
+      self.class.instance_variable_get(:@description)
+    end
+
+    module ClassMethods
+      def description(value = nil)
+        @description = value unless value.nil?
+        @description
+      end
+
+      def command_attrs(attributes = nil)
+        @command_attrs = attributes.dup if attributes
+        @command_attrs ||= {}
+      end
+
+      def command(name, attributes = {}, &block)
+        super(name, command_attrs.merge(attributes), &block)
+      end
+
+      def slash(name, description:, **attributes, &block)
+        application_commands[name.to_s] = Interactions::Command.chat_input(name, description: description, **attributes, &block)
+      end
+
+      def user_command(name, **attributes, &block)
+        application_commands[name.to_s] = Interactions::Command.user(name, **attributes, &block)
+      end
+
+      def message_command(name, **attributes, &block)
+        application_commands[name.to_s] = Interactions::Command.message(name, **attributes, &block)
+      end
+
+      def application_commands
+        @application_commands ||= {}
+      end
+
+      def listener(*names, **attributes, &block)
+        raise ArgumentError, 'Listener requires at least one event name' if names.empty?
+        raise ArgumentError, 'Listener requires a block' unless block
+
+        listeners << { names: names.map(&:to_sym), attributes: attributes, block: block }
+      end
+
+      def listeners
+        @listeners ||= []
+      end
+    end
+  end
+end

data/lib/onyxcord/cogs/extensions.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module OnyxCord
+  class Bot
+    # Extension management: load, unload, and reload cog modules from files.
+    module Extensions
+      # @return [Hash{String => Hash}] loaded extensions keyed by name
+      attr_reader :extensions
+
+      # Load an extension from a file. The file must define a +setup(bot)+ method
+      # that receives the bot and returns a cog instance (or an array of cog instances).
+      # Optionally, the file can define a +teardown(bot)+ method for cleanup.
+      #
+      # @param name [String, Symbol] The extension name (used as key and to resolve file path).
+      # @param path [String, nil] Optional explicit file path. When nil, resolves +extensions/<name>.rb+.
+      # @return [Array<Cog>] the cogs created by the extension.
+      # @raise [ArgumentError] if the extension is already loaded.
+      # @raise [LoadError] if the file cannot be found or does not define +setup+.
+      def load_extension(name, path: nil)
+        @extensions ||= {}
+        name = name.to_s
+        raise ArgumentError, "Extension '#{name}' is already loaded" if @extensions.key?(name)
+
+        path ||= resolve_extension_path(name)
+        raise LoadError, "Extension file not found: #{path}" unless File.exist?(path)
+
+        mod = load_extension_module(path, name)
+
+        raise LoadError, "Extension '#{name}' must define a self.setup(bot) method" unless mod.respond_to?(:setup)
+
+        result = mod.setup(self)
+        cogs = Array(result).select { |obj| obj.is_a?(Cog) }
+
+        @extensions[name] = {
+          path: path,
+          module: mod,
+          cogs: cogs.map { |c| c.respond_to?(:qualified_name) ? c.qualified_name : c.class.name }
+        }
+
+        cogs
+      end
+
+      # Unload an extension by name. Calls +teardown(bot)+ if defined.
+      #
+      # @param name [String, Symbol] The extension name.
+      # @return [true, false] whether the extension was found and unloaded.
+      def unload_extension(name) # rubocop:disable Naming/PredicateMethod
+        @extensions ||= {}
+        name = name.to_s
+        ext = @extensions.delete(name)
+        return false unless ext
+
+        mod = ext[:module]
+        mod.teardown(self) if mod.respond_to?(:teardown)
+
+        ext[:cogs].each { |cog_name| remove_cog(cog_name) }
+
+        true
+      end
+
+      # Reload an extension: unload then load.
+      #
+      # @param name [String, Symbol] The extension name.
+      # @return [Array<Cog>] the cogs created by the reloaded extension.
+      # @raise [ArgumentError] if the extension was not previously loaded.
+      def reload_extension(name)
+        @extensions ||= {}
+        name = name.to_s
+        ext = @extensions[name]
+        raise ArgumentError, "Extension '#{name}' is not loaded" unless ext
+
+        path = ext[:path]
+        unload_extension(name)
+        load_extension(name, path: path)
+      end
+
+      # Load all +.rb+ files from a directory as extensions.
+      #
+      # @param dir [String] The directory path containing extension files.
+      # @return [Array<Cog>] all cogs created from the loaded extensions.
+      def load_extensions(dir)
+        raise ArgumentError, "Extensions directory not found: #{dir}" unless Dir.exist?(dir)
+
+        cogs = []
+        Dir.glob(File.join(dir, '*.rb')).each do |file|
+          name = File.basename(file, '.rb')
+          cogs.concat(load_extension(name, path: file))
+        rescue LoadError, StandardError => e
+          OnyxCord::LOGGER.warn("Failed to load extension '#{name}': #{e.message}") if defined?(OnyxCord::LOGGER)
+        end
+        cogs
+      end
+
+      private
+
+      def resolve_extension_path(name)
+        File.join('extensions', "#{name}.rb")
+      end
+
+      def load_extension_module(path, name)
+        # Create a fresh module for the extension to avoid constant collisions
+        mod = Module.new
+        mod.define_singleton_method(:name) { "OnyxCord::Extensions::#{name.capitalize}" }
+        mod.module_eval(File.read(path), path)
+        mod
+      end
+    end
+  end
+end

data/lib/onyxcord/commands/bot/channels.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 class OnyxCord::Commands::Bot
+  # Channel restriction logic for command bots.
   module Channels
     # @see Commands::Bot#update_channels
     def channels=(channels)

data/lib/onyxcord/commands/bot/execution.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 class OnyxCord::Commands::Bot
+  # Command execution and dispatch logic for the command bot.
   module Execution
     # Returns all aliases for the command with the given name
     # @param name [Symbol] the name of the `Command`