onyxcord 3.2.8 → 4.0.0.beta.2

data/lib/onyxcord/commands/container.rb

@@ -83,6 +83,27 @@ module OnyxCord::Commands
       @commands.delete name
     end
 
+    # Creates a command group. Commands defined inside the block will be prefixed with the group name.
+    #
+    # @example
+    #   group :admin do
+    #     command(:ban) { |event, *args| "Banned #{args.first}" }
+    #     command(:kick) { |event, *args| "Kicked #{args.first}" }
+    #   end
+    #   # Creates :admin_ban and :admin_kick commands
+    #
+    # @param group_name [Symbol] The group prefix.
+    # @param attributes [Hash] Shared attributes applied to all commands in the group.
+    # @yield The block defines commands within the group.
+    # @return [self]
+    def group(group_name, attributes = {}, &block)
+      raise ArgumentError, 'Block required for group' unless block_given?
+
+      proxy = GroupProxy.new(self, group_name, attributes)
+      proxy.instance_exec(&block)
+      self
+    end
+
     # Adds all commands from another container into this one. Existing commands will be overwritten.
     # @param container [Module] A module that `extend`s {CommandContainer} from which the commands will be added.
     def include_commands(container)
@@ -93,6 +114,21 @@ module OnyxCord::Commands
       @commands.merge! handlers
     end
 
+    # Yields each command in this container, flattening subcommands.
+    # @yieldparam name [Symbol] The command name.
+    # @yieldparam cmd [Command] The command object.
+    # @return [self]
+    def walk_commands
+      return self unless block_given?
+
+      @commands&.each do |name, cmd|
+        next if cmd.is_a?(CommandAlias)
+
+        yield name, cmd
+      end
+      self
+    end
+
     # Registers a before or after hook on an existing command.
     # @param command_name [Symbol] The name of the command to hook.
     # @param type [:before, :after] The hook type.
@@ -128,4 +164,19 @@ module OnyxCord::Commands
       end
     end
   end
+
+  # @private
+  # Proxy object used inside a {CommandContainer#group} block to prefix command names.
+  class GroupProxy
+    def initialize(container, group_name, shared_attributes)
+      @container = container
+      @group_name = group_name
+      @shared_attributes = shared_attributes
+    end
+
+    def command(name, attributes = {}, &block)
+      merged = @shared_attributes.merge(attributes)
+      @container.command(:"#{@group_name}_#{name}", merged, &block)
+    end
+  end
 end

data/lib/onyxcord/commands/parser.rb

@@ -12,6 +12,7 @@ module OnyxCord::Commands
     # @!visibility private
     def initialize(name, attributes = {}, &block)
       @name = name
+      @subcommands = {}
       @attributes = {
         # The lowest permission level that can use the command
         permission_level: attributes[:permission_level] || 0,
@@ -65,6 +66,9 @@ module OnyxCord::Commands
         # Block for handling internal exceptions, or a string to respond with
         rescue: attributes[:rescue],
 
+        # Whether the command executes even when a subcommand is provided
+        invoke_without_command: attributes[:invoke_without_command] || false,
+
         # A list of aliases that reference this command
         aliases: attributes[:aliases] || []
       }
@@ -94,6 +98,43 @@ module OnyxCord::Commands
       self
     end
 
+    # Registers a subcommand on this command.
+    # @param name [Symbol] The subcommand name.
+    # @param attributes [Hash] Attributes forwarded to the subcommand.
+    # @yieldparam event [CommandEvent] The event.
+    # @yieldparam args [Array<String>] Remaining arguments.
+    # @return [Command] The newly created subcommand.
+    def subcommand(name, attributes = {}, &block)
+      sub = self.class.new(name, attributes, &block)
+      @subcommands[name] = sub
+      sub
+    end
+
+    # @return [Hash{Symbol => Command}] subcommands registered on this command.
+    attr_reader :subcommands
+
+    # Finds a subcommand by name.
+    # @param name [Symbol, String] The subcommand name.
+    # @return [Command, nil]
+    def find_subcommand(name)
+      @subcommands[name.to_sym]
+    end
+
+    def copy_for(receiver = nil)
+      block = @block
+      copied = self.class.new(@name, @attributes.dup) do |event, *arguments|
+        receiver ? receiver.instance_exec(event, *arguments, &block) : block.call(event, *arguments)
+      end
+      @before_hooks.each { |hook| copied.before { |event, *args| receiver ? receiver.instance_exec(event, *args, &hook) : hook.call(event, *args) } }
+      @after_hooks.each { |hook| copied.after { |event, *args| receiver ? receiver.instance_exec(event, *args, &hook) : hook.call(event, *args) } }
+      @subcommands.each { |name, sub| copied.subcommand(name) { |event, *args| sub.call(event, args) } }
+      copied.instance_variable_set(:@check, proc { |event| receiver.__send__(:passed_cog_command_check?, event) }) if receiver
+      copied.instance_variable_set(:@error_handler, proc { |event, error| receiver.__send__(:handled_cog_command_error?, event, error) }) if receiver
+      copied.instance_variable_set(:@cog_before_invoke, proc { |event| receiver.__send__(:invoke_cog_before_invoke, event) }) if receiver
+      copied.instance_variable_set(:@cog_after_invoke, proc { |event, result| receiver.__send__(:invoke_cog_after_invoke, event, result) }) if receiver
+      copied
+    end
+
     # Calls this command and executes the code inside.
     # @param event [CommandEvent] The event to call the command with.
     # @param arguments [Array<String>] The attributes for the command.
@@ -127,6 +168,10 @@ module OnyxCord::Commands
         end
       end
 
+      return unless @check.nil? || @check.call(event)
+
+      @cog_before_invoke&.call(event)
+
       cancelled = @before_hooks.any? { |hook| hook.call(event, *arguments).is_a?(FalseClass) }
       return if cancelled
 
@@ -134,20 +179,29 @@ module OnyxCord::Commands
       event.drain_into(result)
 
       @after_hooks.each { |hook| hook.call(event, *arguments, result) }
+      @cog_after_invoke&.call(event, result)
 
       result
     rescue LocalJumpError => e # occurs when breaking
       result = e.exit_value
       event.drain_into(result)
     rescue StandardError => e # Something went wrong inside our @block!
-      rescue_value = @attributes[:rescue] || event.bot.attributes[:rescue]
-      if rescue_value
-        event.respond(rescue_value.gsub('%exception%', e.message)) if rescue_value.is_a?(String)
-        rescue_value.call(event, e) if rescue_value.respond_to?(:call)
-      end
+      rescue_value = @attributes[:rescue]
+      return handle_rescue_value(rescue_value, event, e) if rescue_value
+      return if @error_handler&.call(event, e)
+
+      bot_rescue = event.bot.attributes[:rescue]
+      return handle_rescue_value(bot_rescue, event, e) if bot_rescue
 
       raise e
     end
+
+    private
+
+    def handle_rescue_value(rescue_value, event, error)
+      event.respond(rescue_value.gsub('%exception%', error.message)) if rescue_value.is_a?(String)
+      rescue_value.call(event, error) if rescue_value.respond_to?(:call)
+    end
   end
 
   # A command that references another command
@@ -190,10 +244,10 @@ module OnyxCord::Commands
 
       @chain.each_char.with_index do |char, index|
         # Escape character
-        if char == '\\' && !escaped
+        if char == '\\' && !escaped && b_level <= 0
           escaped = true
           next
-        elsif escaped && b_level <= 0
+        elsif escaped
           result += char
           escaped = false
           next

data/lib/onyxcord/commands/rate_limiter.rb

@@ -25,10 +25,10 @@ module OnyxCord::Commands
 
       @bucket.delete_if do |_, limit_hash|
         # Time limit has not run out
-        return false if @time_span && rate_limit_time < (limit_hash[:set_time] + @time_span)
+        next false if @time_span && rate_limit_time < (limit_hash[:set_time] + @time_span)
 
         # Delay has not run out
-        return false if @delay && rate_limit_time < (limit_hash[:last_time] + @delay)
+        next false if @delay && rate_limit_time < (limit_hash[:last_time] + @delay)
 
         true
       end

data/lib/onyxcord/core/bot/application_commands.rb

@@ -13,7 +13,7 @@ module OnyxCord
                  REST::Application.get_global_commands(@token, profile.id)
                end
 
-        JSON.parse(resp).map do |command_data|
+        OnyxCord::Internal::JSON.parse(resp).map do |command_data|
           ApplicationCommand.new(command_data, self, server_id)
         end
       end
@@ -27,38 +27,42 @@ module OnyxCord
                else
                  REST::Application.get_global_command(@token, profile.id, command_id)
                end
-        ApplicationCommand.new(JSON.parse(resp), self, server_id)
+        ApplicationCommand.new(OnyxCord::Internal::JSON.parse(resp), self, server_id)
       end
 
       # @return [OnyxCord::Interactions::Registry]
       def commands
-        @commands ||= ApplicationCommands::Registry.new(self)
+        @commands ||= application_command_registry
+      end
+
+      def application_command_registry
+        @application_command_registry ||= ::OnyxCord::ApplicationCommands::Registry.new(self)
       end
 
       def slash(name, description: nil, **attributes, &block)
-        commands.slash(name, description: description, **attributes, &block)
+        application_command_registry.slash(name, description: description, **attributes, &block)
       end
 
       def user_command(name, **attributes, &block)
-        commands.user(name, **attributes, &block)
+        application_command_registry.user(name, **attributes, &block)
       end
 
       def message_command(name, **attributes, &block)
-        commands.message(name, **attributes, &block)
+        application_command_registry.message(name, **attributes, &block)
       end
 
       def sync_application_commands!(server_id: nil, delete_unknown: false)
-        commands.sync!(server_id: server_id, delete_unknown: delete_unknown)
+        application_command_registry.sync!(server_id: server_id, delete_unknown: delete_unknown)
       end
 
       def bulk_overwrite_global_application_commands(commands)
         response = REST::Application.bulk_overwrite_global_commands(@token, profile.id, commands)
-        JSON.parse(response).map { |data| ApplicationCommand.new(data, self) }
+        OnyxCord::Internal::JSON.parse(response).map { |data| ApplicationCommand.new(data, self) }
       end
 
       def bulk_overwrite_guild_application_commands(server_id, commands)
         response = REST::Application.bulk_overwrite_guild_commands(@token, profile.id, server_id.resolve_id, commands)
-        JSON.parse(response).map { |data| ApplicationCommand.new(data, self, server_id) }
+        OnyxCord::Internal::JSON.parse(response).map { |data| ApplicationCommand.new(data, self, server_id) }
       end
 
       # @yieldparam [OptionBuilder]
@@ -91,7 +95,7 @@ module OnyxCord
                else
                  REST::Application.create_global_command(@token, profile.id, name, description, builder.to_a, default_permission, type, default_member_permissions&.to_s, contexts, nsfw, integration_types)
                end
-        cmd = ApplicationCommand.new(JSON.parse(resp), self, server_id)
+        cmd = ApplicationCommand.new(OnyxCord::Internal::JSON.parse(resp), self, server_id)
 
         if permission_builder.to_a.any?
           raise ArgumentError, 'Permissions can only be set for guild commands' unless server_id
@@ -121,7 +125,7 @@ module OnyxCord
                else
                  REST::Application.edit_global_command(@token, profile.id, command_id, name, description, builder.to_a, default_permission, type, default_member_permissions&.to_s, contexts, nsfw, integration_types)
                end
-        cmd = ApplicationCommand.new(JSON.parse(resp), self, server_id)
+        cmd = ApplicationCommand.new(OnyxCord::Internal::JSON.parse(resp), self, server_id)
 
         if permission_builder.to_a.any?
           raise ArgumentError, 'Permissions can only be set for guild commands' unless server_id
@@ -163,14 +167,14 @@ module OnyxCord
       # @return [Array<ApplicationCommand::Permission>] The permissions for all of the application commands in the given server.
       def application_command_permissions(server_id:)
         response = REST::Application.get_guild_application_command_permissions(@token, profile.id, server_id.resolve_id)
-        JSON.parse(response).flat_map { |data| data['permissions'].map { |inner| ApplicationCommand::Permission.new(inner, data, self) } }
+        OnyxCord::Internal::JSON.parse(response).flat_map { |data| data['permissions'].map { |inner| ApplicationCommand::Permission.new(inner, data, self) } }
       end
 
       # Fetches all the application emojis that the bot can use.
       # @return [Array<Emoji>] Returns an array of emoji objects.
       def application_emojis
         response = REST::Application.list_application_emojis(@token, profile.id)
-        JSON.parse(response)['items'].map { |emoji| Emoji.new(emoji, self) }
+        OnyxCord::Internal::JSON.parse(response)['items'].map { |emoji| Emoji.new(emoji, self) }
       end
 
       # Fetches a single application emoji from its ID.
@@ -178,7 +182,7 @@ module OnyxCord
       # @return [Emoji] The application emoji.
       def application_emoji(emoji_id)
         response = REST::Application.get_application_emoji(@token, profile.id, emoji_id.resolve_id)
-        Emoji.new(JSON.parse(response), self)
+        Emoji.new(OnyxCord::Internal::JSON.parse(response), self)
       end
 
       # Creates a new custom emoji that can be used by this application.
@@ -188,7 +192,7 @@ module OnyxCord
       def create_application_emoji(name:, image:)
         image = image.respond_to?(:read) ? OnyxCord.encode64(image) : image
         response = REST::Application.create_application_emoji(@token, profile.id, name, image)
-        Emoji.new(JSON.parse(response), self)
+        Emoji.new(OnyxCord::Internal::JSON.parse(response), self)
       end
 
       # Edits an existing application emoji.
@@ -197,7 +201,7 @@ module OnyxCord
       # @return [Emoji] Returns the updated emoji object on success.
       def edit_application_emoji(emoji_id, name:)
         response = REST::Application.edit_application_emoji(@token, profile.id, emoji_id.resolve_id, name)
-        Emoji.new(JSON.parse(response), self)
+        Emoji.new(OnyxCord::Internal::JSON.parse(response), self)
       end
 
       # Deletes an existing application emoji.

data/lib/onyxcord/core/bot/messaging.rb

@@ -25,7 +25,7 @@ module OnyxCord
         flags = OnyxCord::MessageComponents.apply_v2_flag(flags, components)
 
         response = REST::Channel.create_message(token, channel, content, tts, embeds, nonce, attachments, allowed_mentions&.to_hash, message_reference, components, flags, enforce_nonce, poll&.to_h)
-        Message.new(JSON.parse(response), self)
+        Message.new(OnyxCord::Internal::JSON.parse(response), self)
       end
 
       # Sends a text message to a channel given its ID and the message's content,
@@ -75,7 +75,7 @@ module OnyxCord
 
         channel = channel.resolve_id
         response = REST::Channel.upload_file(token, channel, file, caption: caption, tts: tts)
-        Message.new(JSON.parse(response), self)
+        Message.new(OnyxCord::Internal::JSON.parse(response), self)
       end
 
       # Gets the users, channels, roles and emoji from a string.

data/lib/onyxcord/core/bot/oauth.rb

@@ -9,7 +9,7 @@ module OnyxCord
       # @param redirect_uris [Array<String>] URIs that Discord should redirect your users to after authorizing.
       # @return [Array(String, String)] your applications' client ID and client secret to be used in OAuth authorization.
       def create_oauth_application(name, redirect_uris)
-        response = JSON.parse(REST.create_oauth_application(@token, name, redirect_uris))
+        response = OnyxCord::Internal::JSON.parse(REST.create_oauth_application(@token, name, redirect_uris))
         [response['id'], response['secret']]
       end
 

data/lib/onyxcord/core/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OnyxCord
-  VERSION = '3.2.8'
+  VERSION = '4.0.0.beta.2'
 end

data/lib/onyxcord/events/interactions/autocomplete.rb

@@ -28,15 +28,13 @@ module OnyxCord::Events
     # @return [String] Name of the currently focused option.
     attr_reader :focused
 
-    # @return [Hash] An empty hash that can be used to return choices by adding K/V pairs.
-    attr_reader :choices
+    # @return [String, Integer, Float, nil] The current value typed by the user (if any).
+    attr_reader :value
 
     # @!visibility private
     def initialize(data, bot)
       super
 
-      @choices = {}
-
       options = data['data']['options']
 
       options = case options[0]['type']
@@ -48,14 +46,31 @@ module OnyxCord::Events
                   options
                 end
 
-      @focused = options.find { |opt| opt.key?('focused') }['name']
+      focused_option = options.find { |opt| opt.key?('focused') }
+      @focused = focused_option['name']
+      @value = focused_option['value']
     end
 
     # Respond to this interaction with autocomplete choices.
-    # @param choices [Array<Hash>, Hash, nil] Autocomplete choices to return.
+    # @param choices [Array<Hash>, Hash] Autocomplete choices to return.
+    #   When a Hash, keys are names and values are the choice values.
+    #   When an Array, each element is a Hash with :name and :value keys.
     def respond(choices:)
       @interaction.show_autocomplete_choices(choices || [])
     end
+
+    # Convenience method to add a single choice and respond.
+    # @param name [String] The display name of the choice.
+    # @param value [String, Integer, Float] The value sent to the bot when selected.
+    def add_choice(name, value)
+      respond(choices: [{ name: name.to_s, value: value }])
+    end
+
+    # Convenience method to respond with multiple name/value pairs.
+    # @param pairs [Hash{String => String, Integer, Float}] Name => Value pairs.
+    def add_choices(pairs)
+      respond(choices: pairs.map { |n, v| { name: n.to_s, value: v } })
+    end
   end
 
   # An event for whenever an application command's permissions are updated.

data/lib/onyxcord/gateway/client.rb

@@ -28,6 +28,7 @@ module OnyxCord
         @compress_mode = compress_mode
         @intents = intents
         @send_limiter = Internal::RateLimiter::Gateway.new
+        @zlib_mutex = Mutex.new
         @connection = nil
         @closed = true
         @pipe_broken = false
@@ -62,6 +63,7 @@ module OnyxCord
 
       def stop
         @should_reconnect = false
+        @intentional_shutdown = true
         close
         nil
       end
@@ -75,8 +77,8 @@ module OnyxCord
       end
 
       def inject_reconnect(url = nil)
-        data = url ? { url: url } : nil
-        handle_message({ op: Internal::Gateway::Opcodes::RECONNECT, d: data }.to_json)
+        data = url ? { op: Internal::Gateway::Opcodes::RECONNECT, d: { url: url } } : { op: Internal::Gateway::Opcodes::RECONNECT, d: nil }
+        handle_message(data.to_json)
       end
 
       def inject_resume(seq)
@@ -153,6 +155,8 @@ module OnyxCord
         @session.invalidate if attempt_resume && @session && !@received_hello
         @instant_reconnect = true
         @should_reconnect = true
+        @heartbeat_task&.stop
+        @heartbeat_task = nil
         close(4000)
       end
 
@@ -226,7 +230,7 @@ module OnyxCord
 
       def find_gateway
         response = REST.gateway(@token)
-        JSON.parse(response)['url']
+        OnyxCord::Internal::JSON.parse(response)['url']
       end
 
       def process_gateway
@@ -267,10 +271,12 @@ module OnyxCord
         end
       rescue Protocol::WebSocket::ClosedError, EOFError => e
         LOGGER.warn("Gateway websocket closed (#{e.class}); reconnecting.")
-        begin
-          @bot.__send__(:raise_event, Events::DisconnectEvent.new(@bot))
-        rescue StandardError
-          nil
+        unless @intentional_shutdown
+          begin
+            @bot.__send__(:raise_event, Events::DisconnectEvent.new(@bot))
+          rescue StandardError
+            nil
+          end
         end
       rescue StandardError => e
         @session&.invalidate unless @received_hello
@@ -303,15 +309,17 @@ module OnyxCord
       def handle_message(msg)
         case @compress_mode
         when :large
-          msg = Zlib::Inflate.inflate(msg) if msg.byteslice(0) == 'x'
+          msg = @zlib_mutex.synchronize { Zlib::Inflate.inflate(msg) } if msg.byteslice(0) == 'x'
         when :stream
-          @zlib_reader << msg
-          return if msg.bytesize < 4 || msg.byteslice(-4, 4) != ZLIB_SUFFIX
+          @zlib_mutex.synchronize do
+            @zlib_reader << msg
+            return if msg.bytesize < 4 || msg.byteslice(-4, 4) != ZLIB_SUFFIX
 
-          msg = @zlib_reader.inflate('')
+            msg = @zlib_reader.inflate('')
+          end
         end
 
-        packet = JSON.parse(msg)
+        packet = OnyxCord::Internal::JSON.parse(msg)
         op = packet['op'].to_i
 
         LOGGER.in(packet)
@@ -374,11 +382,12 @@ module OnyxCord
             reconnect
           else
             @session.invalidate
+            identify
           end
         else
           LOGGER.warn('Op 9 without session!')
+          identify
         end
-        identify
       end
 
       # Op 10
@@ -414,7 +423,7 @@ module OnyxCord
       end
 
       def handle_close(e)
-        @bot.__send__(:raise_event, Events::DisconnectEvent.new(@bot))
+        @bot.__send__(:raise_event, Events::DisconnectEvent.new(@bot)) unless @intentional_shutdown
 
         if e.respond_to?(:code)
           LOGGER.error("WebSocket close frame! Code: #{e.code}")
@@ -454,6 +463,12 @@ module OnyxCord
           # Ignore close errors
         end
 
+        begin
+          @zlib_reader&.finish
+        rescue StandardError
+          nil
+        end
+        @zlib_reader = nil
         @connection = nil
         handle_close(nil)
       end

data/lib/onyxcord/interactions/command.rb

@@ -53,13 +53,38 @@ module OnyxCord
       end
 
       def execute(&block)
-        @executor = block
+        @executor = @receiver ? proc { |context| @receiver.instance_exec(context, &block) } : block
       end
 
       def call(context)
         return unless @executor
+        return unless @check.nil? || @check.call(context, self)
 
-        @executor.call(context)
+        @cog_before_invoke&.call(context, self)
+        result = @executor.call(context)
+        @cog_after_invoke&.call(context, result, self)
+        result
+      rescue StandardError => e
+        return if @error_handler&.call(context, e, self)
+
+        raise e
+      end
+
+      def copy_for(receiver = nil)
+        copied = self.class.new(@name, description: @description, type: @type, **@attributes, &@block)
+        copied.instance_variable_set(:@receiver, receiver)
+        copied.instance_variable_set(:@check, proc { |context, command| receiver.__send__(:passed_cog_application_command_check?, context, command) }) if receiver
+        copied.instance_variable_set(:@error_handler, proc { |context, error, command| receiver.__send__(:handled_cog_application_command_error?, context, error, command) }) if receiver
+        copied.instance_variable_set(:@cog_before_invoke, proc { |context, command| receiver.__send__(:invoke_cog_application_before_invoke, context, command) }) if receiver
+        copied.instance_variable_set(:@cog_after_invoke, proc { |context, result, command| receiver.__send__(:invoke_cog_application_after_invoke, context, result, command) }) if receiver
+        copied.instance_variable_set(:@options, @options.map(&:dup))
+
+        if @executor
+          executor = @executor
+          copied.execute { |context| receiver ? receiver.instance_exec(context, &executor) : executor.call(context) }
+        end
+
+        copied
       end
 
       def to_h

data/lib/onyxcord/interactions/internal/application_command.rb

@@ -97,7 +97,7 @@ module OnyxCord
     def permissions(server_id: nil)
       raise ArgumentError, 'A server ID must be provided for global application commands' if @server_id.nil? && server_id.nil?
 
-      response = JSON.parse(REST::Application.get_application_command_permissions(@bot.token, @bot.profile.id, @server_id || server_id&.resolve_id, @id))
+      response = OnyxCord::Internal::JSON.parse(REST::Application.get_application_command_permissions(@bot.token, @bot.profile.id, @server_id || server_id&.resolve_id, @id))
       response['permissions'].map { |permission| Permission.new(permission, response, @bot) }
     rescue OnyxCord::Errors::UnknownError
       # If there aren't any explicit overwrites configured for the command, the response is a 400.

data/lib/onyxcord/interactions/registry.rb

@@ -8,6 +8,8 @@ module OnyxCord
       def initialize(bot)
         @bot = bot
         @commands = {}
+        @pending_sync = nil
+        @sync_mutex = Mutex.new
       end
 
       def slash(name, description:, **attributes, &block)
@@ -23,11 +25,16 @@ module OnyxCord
       end
 
       def register(command)
+        command.parse(&command.block) if command.block && command.options.empty?
         @commands[command.name] = command
         wire_handler(command)
         command
       end
 
+      # Immediately sync all commands to Discord.
+      # @param server_id [Integer, String, nil] Guild ID for guild commands, or nil for global.
+      # @param delete_unknown [Boolean] Whether to remove commands not in the registry.
+      # @return [void]
       def sync!(server_id: nil, delete_unknown: false) # rubocop:disable Lint/UnusedMethodArgument
         payload = @commands.values.map(&:to_h)
 
@@ -38,6 +45,35 @@ module OnyxCord
         end
       end
 
+      # Sync global application commands.
+      # @return [void]
+      def sync_global_commands
+        sync!(server_id: nil)
+      end
+
+      # Sync guild application commands.
+      # @param server_id [Integer, String] The guild ID.
+      # @return [void]
+      def sync_server_commands(server_id)
+        sync!(server_id: server_id)
+      end
+
+      # Schedule a debounced sync. Multiple calls within the delay window
+      # are collapsed into a single sync. Default delay is 2 seconds.
+      # @param delay [Numeric] Seconds to wait before syncing.
+      # @param server_id [Integer, String, nil] Guild ID, or nil for global.
+      # @return [Thread, nil] The timer thread, or nil if cancelled.
+      def schedule_delayed_command_sync(delay: 2, server_id: nil)
+        @sync_mutex.synchronize do
+          @pending_sync&.kill if @pending_sync.is_a?(Thread)
+          @pending_sync = Thread.new do
+            sleep(delay)
+            @sync_mutex.synchronize { @pending_sync = nil }
+            sync!(server_id: server_id)
+          end
+        end
+      end
+
       private
 
       def wire_handler(command)