discorb 0.12.2 → 0.13.1

data/lib/discorb/guild.rb

@@ -28,7 +28,7 @@ module Discorb
     attr_reader :features
     # @return [:none, :elevated] The MFA level of the guild.
     attr_reader :mfa_level
-    # @return [Discorb::Guild::SystemChannelFlag] The flag for the system channel.
+    # @return [Discorb::SystemChannelFlag] The flag for the system channel.
     attr_reader :system_channel_flags
     # @return [Time] Time that representing when bot has joined the guild.
     attr_reader :joined_at
@@ -96,6 +96,9 @@ module Discorb
     # @return [Boolean] Whether the guild is available.
     attr_reader :available
     alias available? available
+    # @return [Dictionary{Discorb::Snowflake => Discorb::ScheduledEvent}] A dictionary of scheduled events in the guild.
+    attr_reader :scheduled_events
+    alias events scheduled_events
 
     # @!attribute [r] afk_channel
     #   @return [Discorb::VoiceChannel] The AFK channel for this guild.
@@ -159,8 +162,9 @@ module Discorb
 
     #
     # Leave the guild.
-    # @macro async
-    # @macro http
+    # @async
+    #
+    # @return [Async::Task<void>] The task.
     #
     def leave!
       Async do
@@ -169,10 +173,115 @@ module Discorb
       end
     end
 
+    #
+    # Fetch scheduled events for the guild.
+    # @async
+    #
+    # @param [Boolean] with_user_count Whether to include the user count in the events.
+    #   Defaults to `true`.
+    #
+    # @return [Array<Discorb::ScheduledEvent>] The events for the guild.
+    #
+    def fetch_scheduled_events(with_user_count: true)
+      Async do
+        _resp, events = @client.http.get("/guilds/#{@id}/scheduled-events?with_user_count=#{with_user_count}").wait
+        @scheduled_events = events.map { |e| ScheduledEvent.new(@client, e) }
+      end
+    end
+
+    #
+    # Fetch the scheduled event by ID.
+    # @async
+    #
+    # @param [#to_s] id The ID of the scheduled event.
+    #
+    # @return [Async::Task<Discorb::ScheduledEvent>] The event with the given ID.
+    # @return [Async::Task<nil>] If no event with the given ID exists.
+    #
+    def fetch_scheduled_event(id)
+      Async do
+        _resp, event = @client.http.get("/guilds/#{@id}/scheduled-events/#{id}").wait
+      rescue Discorb::NotFoundError
+        return nil
+      else
+        ScheduledEvent.new(@client, event)
+      end
+    end
+
+    #
+    # Create a scheduled event for the guild.
+    # @async
+    #
+    # @param [:stage_instance, :voice, :external] type The type of event to create.
+    # @param [String] name The name of the event.
+    # @param [String] description The description of the event.
+    # @param [Time] start_time The start time of the event.
+    # @param [Time, nil] end_time The end time of the event. Defaults to `nil`.
+    # @param [Discorb::Channel, Discorb::Snowflake, nil] channel The channel to run the event in.
+    # @param [String, nil] location The location of the event. Defaults to `nil`.
+    # @param [:guild_only] privacy_level The privacy level of the event. This must be `:guild_only`.
+    #
+    # @return [Async::Task<Discorb::ScheduledEvent>] The created event.
+    #
+    def create_scheduled_event(
+      type,
+      name,
+      description,
+      start_time,
+      end_time = nil,
+      privacy_level: :guild_only,
+      location: nil,
+      channel: nil
+    )
+      Async do
+        payload = case type
+          when :stage_instance
+            raise ArgumentError, "channel must be provided for stage_instance events" unless channel
+            {
+              name: name,
+              description: description,
+              scheduled_start_time: start_time.iso8601,
+              scheduled_end_time: end_time&.iso8601,
+              privacy_level: Discorb::ScheduledEvent.privacy_level.key(privacy_level),
+              channel_id: channel&.id,
+              entity_type: Discorb::ScheduledEvent.entity_type.key(:stage_instance),
+            }
+          when :voice
+            raise ArgumentError, "channel must be provided for voice events" unless channel
+            {
+              name: name,
+              description: description,
+              scheduled_start_time: start_time.iso8601,
+              scheduled_end_time: end_time&.iso8601,
+              privacy_level: Discorb::ScheduledEvent.privacy_level.key(privacy_level),
+              channel_id: channel&.id,
+              entity_type: Discorb::ScheduledEvent.entity_type.key(:voice),
+            }
+          when :external
+            raise ArgumentError, "location must be provided for external events" unless location
+            raise ArgumentError, "end_time must be provided for external events" unless end_time
+            {
+              name: name,
+              description: description,
+              scheduled_start_time: start_time.iso8601,
+              scheduled_end_time: end_time.iso8601,
+              privacy_level: Discorb::ScheduledEvent.privacy_level.key(privacy_level),
+              entity_type: Discorb::ScheduledEvent.entity_type.key(:external),
+              entity_metadata: {
+                location: location,
+              },
+            }
+          else
+            raise ArgumentError, "Invalid scheduled event type: #{type}"
+          end
+        _resp, event = @client.http.post("/guilds/#{@id}/scheduled-events", payload).wait
+        Discorb::ScheduledEvent.new(@client, event)
+      end
+    end
+
     #
     # Fetch emoji list of the guild.
-    # @macro async
-    # @macro http
+    # @async
     # @note This querys the API every time. We recommend using {#emojis} instead.
     #
     # @return [Async::Task<Discorb::Dictionary{Discorb::Snowflake => Discorb::CustomEmoji}>] A dictionary of emoji in the guild.
@@ -195,8 +304,7 @@ module Discorb
 
     #
     # Fetch emoji id of the guild.
-    # @macro async
-    # @macro http
+    # @async
     # @note This querys the API every time. We recommend using {#emojis} instead.
     #
     # @param [#to_s] id The emoji id.
@@ -210,8 +318,7 @@ module Discorb
 
     #
     # Create a custom emoji.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @param [#to_s] name The name of the emoji.
     # @param [Discorb::Image] image The image of the emoji.
@@ -233,8 +340,7 @@ module Discorb
 
     #
     # Fetch webhooks of the guild.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @return [Async::Task<Array<Discorb::Webhook>>] A list of webhooks in the guild.
     #
@@ -247,8 +353,7 @@ module Discorb
 
     #
     # Fetch audit log of the guild.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @return [Async::Task<Discorb::AuditLog>] The audit log of the guild.
     #
@@ -261,8 +366,7 @@ module Discorb
 
     #
     # Fetch channels of the guild.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @return [Async::Task<Array<Discorb::Channel>>] A list of channels in the guild.
     #
@@ -275,8 +379,7 @@ module Discorb
 
     #
     # Create a new text channel.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @param [String] name The name of the channel.
     # @param [String] topic The topic of the channel.
@@ -322,8 +425,7 @@ module Discorb
 
     #
     # Create a new voice channel.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @param [String] name The name of the channel.
     # @param [Integer] bitrate The bitrate of the channel.
@@ -364,8 +466,7 @@ module Discorb
     end
 
     # Create a new category channel.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @param [String] name The name of the channel.
     # @param [Integer] position The position of the channel.
@@ -402,8 +503,7 @@ module Discorb
 
     #
     # Create a new stage channel.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @param [String] name The name of the channel.
     # @param [Integer] bitrate The bitrate of the channel.
@@ -440,8 +540,7 @@ module Discorb
 
     #
     # Create a new news channel.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @param [String] name The name of the channel.
     # @param [String] topic The topic of the channel.
@@ -486,8 +585,7 @@ module Discorb
 
     #
     # Fetch a list of active threads in the guild.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @return [Async::Task<Array<Discorb::ThreadChannel>>] The list of threads.
     #
@@ -500,8 +598,7 @@ module Discorb
 
     #
     # Fetch a member in the guild.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @param [#to_s] id The ID of the member to fetch.
     #
@@ -519,8 +616,7 @@ module Discorb
     end
 
     # Fetch members in the guild.
-    # @macro async
-    # @macro http
+    # @async
     # @macro members_intent
     #
     # @param [Integer] limit The maximum number of members to fetch, 0 for all.
@@ -553,8 +649,7 @@ module Discorb
 
     #
     # Search for members by name in the guild.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @param [String] name The name of the member to search for.
     # @param [Integer] limit The maximum number of members to return.
@@ -570,8 +665,7 @@ module Discorb
 
     #
     # Almost the same as {#fetch_members_named}, but returns a single member.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @return [Async::Task<Discorb::Member>] The member.
     # @return [Async::Task<nil>] If the member is not found.
@@ -584,10 +678,13 @@ module Discorb
 
     #
     # Change nickname of client member.
+    # @async
     #
     # @param [String] nickname The nickname to set.
     # @param [String] reason The reason for changing the nickname.
     #
+    # @return [Async::Task<void>] The task.
+    #
     def edit_nickname(nickname, reason: nil)
       Async do
         @client.http.patch("/guilds/#{@id}/members/@me/nick", { nick: nickname }, audit_log_reason: reason).wait
@@ -600,12 +697,13 @@ module Discorb
 
     #
     # Kick a member from the guild.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @param [Discorb::Member] member The member to kick.
     # @param [String] reason The reason for kicking the member.
     #
+    # @return [Async::Task<void>] The task.
+    #
     def kick_member(member, reason: nil)
       Async do
         @client.http.delete("/guilds/#{@id}/members/#{member.id}", audit_log_reason: reason).wait
@@ -614,8 +712,7 @@ module Discorb
 
     #
     # Fetch a list of bans in the guild.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @return [Async::Task<Array<Discorb::Guild::Ban>>] The list of bans.
     #
@@ -628,8 +725,7 @@ module Discorb
 
     #
     # Fetch a ban in the guild.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @param [Discorb::User] user The user to fetch.
     #
@@ -648,8 +744,7 @@ module Discorb
 
     #
     # Checks the user was banned from the guild.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @param [Discorb::User] user The user to check.
     #
@@ -663,8 +758,7 @@ module Discorb
 
     #
     # Ban a member from the guild.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @param [Discorb::Member] member The member to ban.
     # @param [Integer] delete_message_days The number of days to delete messages.
@@ -683,12 +777,13 @@ module Discorb
 
     #
     # Unban a user from the guild.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @param [Discorb::User] user The user to unban.
     # @param [String] reason The reason for unbanning the user.
     #
+    # @return [Async::Task<void>] The task.
+    #
     def unban_user(user, reason: nil)
       Async do
         @client.http.delete("/guilds/#{@id}/bans/#{user.id}", audit_log_reason: reason).wait
@@ -697,8 +792,7 @@ module Discorb
 
     #
     # Fetch a list of roles in the guild.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @return [Async::Task<Array<Discorb::Role>>] The list of roles.
     #
@@ -711,8 +805,7 @@ module Discorb
 
     #
     # Create a role in the guild.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @param [String] name The name of the role.
     # @param [Discorb::Color] color The color of the role.
@@ -738,8 +831,7 @@ module Discorb
 
     #
     # Fetch how many members will be pruned.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @param [Integer] days The number of days to prune.
     # @param [Array<Discorb::Role>] roles The roles that include for pruning.
@@ -760,8 +852,7 @@ module Discorb
 
     #
     # Prune members from the guild.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @param [Integer] days The number of days to prune.
     # @param [Array<Discorb::Role>] roles The roles that include for pruning.
@@ -780,8 +871,7 @@ module Discorb
 
     #
     # Fetch voice regions that are available in the guild.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @return [Async::Task<Array<Discorb::VoiceRegion>>] The available voice regions.
     #
@@ -794,8 +884,7 @@ module Discorb
 
     #
     # Fetch invites in the guild.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @return [Async::Task<Array<Invite>>] The invites.
     #
@@ -808,8 +897,7 @@ module Discorb
 
     #
     # Fetch integrations in the guild.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @return [Async::Task<Array<Discorb::Integration>>] The integrations.
     #
@@ -822,8 +910,7 @@ module Discorb
 
     #
     # Fetch the widget of the guild.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @return [Async::Task<Discorb::Guild::Widget>] The widget.
     #
@@ -836,8 +923,7 @@ module Discorb
 
     #
     # Fetch the vanity URL of the guild.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @return [Async::Task<Discorb::Guild::VanityInvite>] The vanity URL.
     #
@@ -850,10 +936,9 @@ module Discorb
 
     #
     # Fetch the welcome screen of the guild.
-    # @macro async
-    # @macro http
+    # @async
     #
-    # @return [Async::Task<Discorb::Guild::WelcomeScreen>] The welcome screen.
+    # @return [Async::Task<Discorb::WelcomeScreen>] The welcome screen.
     #
     def fetch_welcome_screen
       Async do
@@ -864,8 +949,7 @@ module Discorb
 
     #
     # Fetch stickers in the guild.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @return [Async::Task<Array<Discorb::Sticker::GuildSticker>>] The stickers.
     #
@@ -878,8 +962,7 @@ module Discorb
 
     #
     # Fetch the sticker by ID.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @param [#to_s] id The ID of the sticker.
     #
@@ -898,8 +981,7 @@ module Discorb
 
     #
     # Fetch templates in the guild.
-    # @macro async
-    # @macro http
+    # @async
     #
     # @return [Async::Task<Discorb::GuildTemplate>] The templates.
     #
@@ -1001,14 +1083,15 @@ module Discorb
 
       #
       # Edit the widget.
-      # @macro async
-      # @macro http
+      # @async
       # @macro edit
       #
       # @param [Boolean] enabled Whether the widget is enabled.
       # @param [Discorb::GuildChannel] channel The channel.
       # @param [String] reason The reason for editing the widget.
       #
+      # @return [Async::Task<void>] The task.
+      #
       def edit(enabled: nil, channel: nil, reason: nil)
         Async do
           payload = {}
@@ -1143,6 +1226,7 @@ module Discorb
       @presences = Dictionary.new(data[:presences].map { |pr| [Snowflake.new(pr[:user][:id]), Presence.new(@client, pr)] }.to_h)
       @max_presences = data[:max_presences]
       @stage_instances = Dictionary.new(data[:stage_instances].map { |s| [Snowflake.new(s[:id]), StageInstance.new(@client, s)] }.to_h)
+      @scheduled_events = Dictionary.new(data[:guild_scheduled_events].map { |s| [Snowflake.new(s[:id]), ScheduledEvent.new(@client, s)] }.to_h)
       @data.update(data)
     end
   end
@@ -1155,12 +1239,14 @@ module Discorb
   # |`1 << 0`|`:member_join`|
   # |`1 << 1`|`:server_boost`|
   # |`1 << 2`|`:setup_tips`|
+  # |`1 << 3`|`:join_stickers`|
   #
   class SystemChannelFlag < Flag
     @bits = {
       member_join: 0,
       server_boost: 1,
       setup_tips: 2,
+      join_stickers: 3,
     }.freeze
   end
 
@@ -1253,8 +1339,7 @@ module Discorb
 
       #
       # Edits the welcome screen.
-      # @macro async
-      # @macro http
+      # @async
       # @macro edit
       #
       # @param [Boolean] enabled Whether the welcome screen is enabled.
@@ -1262,12 +1347,14 @@ module Discorb
       # @param [String] description The description of the welcome screen.
       # @param [String] reason The reason for editing the welcome screen.
       #
-      def edit(enabled: :unset, channels: :unset, description: :unset, reason: nil)
+      # @return [Async::Task<void>] The task.
+      #
+      def edit(enabled: Discorb::Unset, channels: Discorb::Unset, description: Discorb::Unset, reason: nil)
         Async do
           payload = {}
-          payload[:enabled] = enabled unless enabled == :unset
-          payload[:welcome_channels] = channels.map(&:to_hash) unless channels == :unset
-          payload[:description] = description unless description == :unset
+          payload[:enabled] = enabled unless enabled == Discorb::Unset
+          payload[:welcome_channels] = channels.map(&:to_hash) unless channels == Discorb::Unset
+          payload[:description] = description unless description == Discorb::Unset
           @client.http.patch("/guilds/#{@guild.id}/welcome-screen", payload, audit_log_reason: reason).wait
         end
       end

data/lib/discorb/guild_template.rb

@@ -45,18 +45,19 @@ module Discorb
 
     #
     # Edit the template.
-    # @macro async
-    # @macro http
+    # @async
     # @macro edit
     #
     # @param [String] name The new name of the template.
     # @param [String] description The new description of the template.
     #
-    def edit(name = nil, description = :unset)
+    # @return [Async::Task<void>] The task.
+    #
+    def edit(name = nil, description = Discorb::Unset)
       Async do
         payload = {}
         payload[:name] = name if name
-        payload[:description] = description if description != :unset
+        payload[:description] = description if description != Discorb::Unset
         @client.http.patch("/guilds/#{@source_guild_id}/templates/#{@code}", payload).wait
       end
     end
@@ -65,8 +66,9 @@ module Discorb
 
     #
     # Update the template.
-    # @macro async
-    # @macro http
+    # @async
+    #
+    # @return [Async::Task<void>] The task.
     #
     def update
       Async do
@@ -77,8 +79,9 @@ module Discorb
 
     #
     # Delete the template.
-    # @macro async
-    # @macro http
+    # @async
+    #
+    # @return [Async::Task<void>] The task.
     #
     def delete!
       Async do
@@ -98,7 +101,7 @@ module Discorb
       attr_reader :afk_timeout
       # @return [Discorb::Dictionary{Discorb::Snowflake => Discorb::Role}] A dictionary of roles in the guild.
       attr_reader :roles
-      # @return [Discorb::Guild::SystemChannelFlag] The flag for the system channel.
+      # @return [Discorb::SystemChannelFlag] The flag for the system channel.
       attr_reader :system_channel_flags
       # @return [Discorb::Dictionary{Discorb::Snowflake => Discorb::GuildChannel}] A dictionary of channels in the guild.
       attr_reader :channels