Class: Discordrb::ScheduledEvent

Inherits:
Object
  • Object
show all
Includes:
IDObject
Defined in:
lib/discordrb/data/scheduled_event.rb

Overview

A scheduled event for an occurrence on a server.

Defined Under Namespace

Classes: RecurrenceRule

Constant Summary collapse

STATUSES =

Map of status types.

{
  scheduled: 1,
  active: 2,
  completed: 3,
  canceled: 4
}.freeze
ENTITY_TYPES =

Map of entity types.

{
  stage: 1,
  voice: 2,
  external: 3
}.freeze

Instance Attribute Summary collapse

Attributes included from IDObject

#id

Instance Method Summary collapse

Methods included from IDObject

#==, #creation_time, synthesise

Instance Attribute Details

#cover_id ⇒ String? (readonly)

Returns the image hash of the scheduled event's cover image.

Returns:

  • (String, nil) —

    the image hash of the scheduled event's cover image.



36
37
38
 
# File 'lib/discordrb/data/scheduled_event.rb', line 36

def cover_id
  @cover_id
end

#description ⇒ String? (readonly)

Returns the description of the scheduled event. Between 1-1000 characters.

Returns:

  • (String, nil) —

    the description of the scheduled event. Between 1-1000 characters.



48
49
50
 
# File 'lib/discordrb/data/scheduled_event.rb', line 48

def description
  @description
end

#end_time ⇒ Time? (readonly)

Returns the time at when the scheduled event will end.

Returns:

  • (Time, nil) —

    the time at when the scheduled event will end.



30
31
32
 
# File 'lib/discordrb/data/scheduled_event.rb', line 30

def end_time
  @end_time
end

#entity_id ⇒ Integer? (readonly)

Returns the ID of the entity associated with the scheduled event.

Returns:

  • (Integer, nil) —

    the ID of the entity associated with the scheduled event.



39
40
41
 
# File 'lib/discordrb/data/scheduled_event.rb', line 39

def entity_id
  @entity_id
end

#entity_type ⇒ Integer (readonly)

Returns the type of the entity that is assoicated with the scheduled event.

Returns:

  • (Integer) —

    the type of the entity that is assoicated with the scheduled event.



45
46
47
 
# File 'lib/discordrb/data/scheduled_event.rb', line 45

def entity_type
  @entity_type
end

#location ⇒ String? (readonly)

Returns the external location of the scheduled event.

Returns:

  • (String, nil) —

    the external location of the scheduled event.



33
34
35
 
# File 'lib/discordrb/data/scheduled_event.rb', line 33

def location
  @location
end

#name ⇒ String (readonly)

Returns the name of the scheduled event.

Returns:

  • (String) —

    the name of the scheduled event.



24
25
26
 
# File 'lib/discordrb/data/scheduled_event.rb', line 24

def name
  @name
end

#recurrence_rule ⇒ RecurrenceRule? (readonly)

Returns the definition for how often this scheduled event should repeat.

Returns:

  • (RecurrenceRule, nil) —

    the definition for how often this scheduled event should repeat.



51
52
53
 
# File 'lib/discordrb/data/scheduled_event.rb', line 51

def recurrence_rule
  @recurrence_rule
end

#start_time ⇒ Time (readonly)

Returns the time at when the scheduled event has been scheduled to start.

Returns:

  • (Time) —

    the time at when the scheduled event has been scheduled to start.



42
43
44
 
# File 'lib/discordrb/data/scheduled_event.rb', line 42

def start_time
  @start_time
end

#status ⇒ Integer (readonly)

Returns the current status of the scheduled event.

Returns:

  • (Integer) —

    the current status of the scheduled event.



27
28
29
 
# File 'lib/discordrb/data/scheduled_event.rb', line 27

def status
  @status
end

Instance Method Details

#active? ⇒ true, false

Returns whether the scheduled event is currently taking place.

Returns:

  • (true, false) —

    whether the scheduled event is currently taking place.



107
108
109
110
111
 
# File 'lib/discordrb/data/scheduled_event.rb', line 107

STATUSES.each do |name, value|
  define_method("#{name}?") do
    @status == value
  end
end

#cancel(reason: nil) ⇒ nil

Cancel the scheduled event. This cannot be undone.

Parameters:

  • reason (String, nil) (defaults to: nil) —

    The reason for cancelling the event.

Returns:

  • (nil) 


137
138
139
140
141
 
# File 'lib/discordrb/data/scheduled_event.rb', line 137

def cancel(reason: nil)
  raise 'cannot cancel this event' unless scheduled?

  modify(status: STATUSES[:canceled], reason: reason)
end

#canceled? ⇒ true, false

Returns whether the scheduled event has been canceled.

Returns:

  • (true, false) —

    whether the scheduled event has been canceled.



107
108
109
110
111
 
# File 'lib/discordrb/data/scheduled_event.rb', line 107

STATUSES.each do |name, value|
  define_method("#{name}?") do
    @status == value
  end
end

#channel ⇒ Channel?

Get the channel in which the scheduled event will be hosted. This can be nil if the type is external.

Returns:

  • (Channel, nil) —

    The channel where the scheduled event will take place, or nil if there isn't one.



81
82
83
 
# File 'lib/discordrb/data/scheduled_event.rb', line 81

def channel
  @bot.channel(@channel_id) if @channel_id
end

#completed? ⇒ true, false

Returns whether the scheduled event has finished taking place.

Returns:

  • (true, false) —

    whether the scheduled event has finished taking place.



107
108
109
110
111
 
# File 'lib/discordrb/data/scheduled_event.rb', line 107

STATUSES.each do |name, value|
  define_method("#{name}?") do
    @status == value
  end
end

#cover_url(format: 'webp', size: 4096) ⇒ String?

Utility method to get a scheduled event's cover image URL.

Parameters:

  • format (String) (defaults to: 'webp') —

    The URL will default to webp. You can otherwise specify one of jpg or png to override this.

  • size (Integer, nil) (defaults to: 4096) —

    The URL will default to 4096. You can otherwise specify any number that's a power of two to override this.

Returns:

  • (String, nil) —

    The URL to the scheduled event's cover image, or nil if the scheduled event doesn't have a cover image set.



95
96
97
 
# File 'lib/discordrb/data/scheduled_event.rb', line 95

def cover_url(format: 'webp', size: 4096)
  API.scheduled_event_cover_url(@id, @cover_id, format, size) if @cover_id
end

#creator ⇒ User?

Get the user who was responsible for the creation of the scheduled event.

Returns:

  • (User, nil) —

    The user who was responsible for the creation of the scheduled event.



75
76
77
 
# File 'lib/discordrb/data/scheduled_event.rb', line 75

def creator
  @bot.user(@creator_id) if @creator_id
end

#delete(reason: nil) ⇒ nil

Delete the scheduled event. Use this with caution, as it cannot be undone.

Parameters:

  • reason (String, nil) (defaults to: nil) —

    The reason to show in the audit log for deleting the scheduled event.

Returns:

  • (nil) 


201
202
203
204
205
 
# File 'lib/discordrb/data/scheduled_event.rb', line 201

def delete(reason: nil)
  API::Server.delete_scheduled_event(@bot.token, @server_id, @id, reason: reason)
  @server&.delete_scheduled_event(@id)
  nil
end

#end(reason: nil) ⇒ nil

End the scheduled event. This cannot be undone.

Parameters:

  • reason (String, nil) (defaults to: nil) —

    The reason for ending the event.

Returns:

  • (nil) 


146
147
148
149
150
 
# File 'lib/discordrb/data/scheduled_event.rb', line 146

def end(reason: nil)
  raise 'cannot end this event' unless active?

  modify(status: STATUSES[:completed], reason: reason)
end

#external? ⇒ true, false

Returns whether the scheduled event will take place in an external location.

Returns:

  • (true, false) —

    whether the scheduled event will take place in an external location.



119
120
121
122
123
 
# File 'lib/discordrb/data/scheduled_event.rb', line 119

ENTITY_TYPES.each do |name, value|
  define_method("#{name}?") do
    @entity_type == value
  end
end

#modify(name: :undef, channel: :undef, location: :undef, start_time: :undef, end_time: :undef, description: :undef, entity_type: :undef, status: :undef, cover: :undef, recurrence_rule: :undef, reason: nil) {|builder| ... } ⇒ nil

Edit the properties of the scheduled event.

Parameters:

  • name (String) (defaults to: :undef) —

    The new 1-100 character name of the scheduled event.

  • channel (Integer, Channel, String, nil) (defaults to: :undef) —

    The new channel of the scheduled event.

  • location (String, nil) (defaults to: :undef) —

    The new location of the scheduled event.

  • start_time (Time) (defaults to: :undef) —

    The new start time of the scheduled event.

  • end_time (Time) (defaults to: :undef) —

    The new end time of the scheduled event.

  • description (String, nil) (defaults to: :undef) —

    The new 1-100 character description of the scheduled event.

  • entity_type (Integer, Symbol) (defaults to: :undef) —

    The new entity type of the scheduled event.

  • status (Integer, Symbol) (defaults to: :undef) —

    The new status of the scheduled event.

  • cover (File, #read) (defaults to: :undef) —

    The new cover image of the scheduled event.

  • recurrence_rule (#to_h, nil) (defaults to: :undef) —

    The new recurrence rule of the scheduled event.

  • reason (String, nil) (defaults to: nil) —

    The audit log reason for updating the scheduled event.

Yield Parameters:

Returns:

  • (nil) 


166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
 
# File 'lib/discordrb/data/scheduled_event.rb', line 166

def modify(
  name: :undef, channel: :undef, location: :undef, start_time: :undef, end_time: :undef,
  description: :undef, entity_type: :undef, status: :undef, cover: :undef,
  recurrence_rule: :undef, reason: nil
)
  data = {
    name: name,
    channel_id: channel == :undef ? channel : channel&.resolve_id,
    entity_metadata: location == :undef ? location : { location: },
    scheduled_end_time: end_time == :undef ? end_time : end_time&.iso8601,
    scheduled_start_time: start_time == :undef ? start_time : start_time&.iso8601,
    description: description,
    entity_type: entity_type == :undef ? entity_type : ENTITY_TYPES[type] || type,
    status: status == :undef ? status : STATUSES[status] || status,
    image: cover.respond_to?(:read) ? Discordrb.encode64(cover) : cover,
    recurrence_rule: recurrence_rule == :undef ? recurrence_rule : recurrence_rule&.to_h,
    reason: reason
  }

  if block_given?
    yield((builder = RecurrenceRule::Builder.new))
    raise 'An `interval` must be provided' unless builder.interval?
    raise 'A `frequency` must be provided' unless builder.frequency?
    raise 'A `start_time` must be provided' unless builder.start_time?

    builder[:recurrence_rule] = builder.to_h
  end

  update_data(JSON.parse(API::Server.update_scheduled_event(@bot.token, @server_id, @id, **data)))
  nil
end

#scheduled? ⇒ true, false

Returns whether the scheduled event has been scheduled to take place.

Returns:

  • (true, false) —

    whether the scheduled event has been scheduled to take place.



107
108
109
110
111
 
# File 'lib/discordrb/data/scheduled_event.rb', line 107

STATUSES.each do |name, value|
  define_method("#{name}?") do
    @status == value
  end
end

#server ⇒ Server

Get the server that the scheduled event originates from.

Returns:

  • (Server) —

    The server that the scheduled event originates from.



69
70
71
 
# File 'lib/discordrb/data/scheduled_event.rb', line 69

def server
  @server ||= @bot.server(@server_id)
end

#stage? ⇒ true, false

Returns whether the scheduled event will take place in a stage channel.

Returns:

  • (true, false) —

    whether the scheduled event will take place in a stage channel.



119
120
121
122
123
 
# File 'lib/discordrb/data/scheduled_event.rb', line 119

ENTITY_TYPES.each do |name, value|
  define_method("#{name}?") do
    @entity_type == value
  end
end

#start(reason: nil) ⇒ nil

Start the scheduled event.

Parameters:

  • reason (String, nil) (defaults to: nil) —

    The reason for starting the event.

Returns:

  • (nil) 


128
129
130
131
132
 
# File 'lib/discordrb/data/scheduled_event.rb', line 128

def start(reason: nil)
  raise 'cannot start this event' unless scheduled?

  modify(status: STATUSES[:active], reason: reason)
end

#url ⇒ String

Get a URL that will display an embed in the Discord client containing information about the scheduled event.

Returns:

  • (String) —

    A URL that will display an embed containing a brief overview about the scheduled event's information.



87
88
89
 
# File 'lib/discordrb/data/scheduled_event.rb', line 87

def url
  "https://discord.com/events/#{@server_id}/#{@id}"
end

#user_count ⇒ Integer Also known as: subscriber_count

Get the total amount of users who are subscribed to the scheduled event.

Returns:

  • (Integer) —

    The total amount of users who are currently subscribed to the scheduled event.



209
210
211
 
# File 'lib/discordrb/data/scheduled_event.rb', line 209

def user_count
  @user_count ||= JSON.parse(API::Server.get_scheduled_event(@bot.token, @server_id, @id, with_user_count: true))['user_count']
end

#users(limit: 100, member: false) ⇒ Array<User, Member> Also known as: subscribers

Get the users who are subscribed to the scheduled event.

Parameters:

  • limit (Integer, nil) (defaults to: 100) —

    The limit (nil for no limit) of how many subscribers to return.

  • member (true, false) (defaults to: false) —

    Whether to return subscribers as server members, when applicable.

Returns:

  • (Array<User, Member>) —

    the users or members that have subscribed to the scheduled event.



219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
 
# File 'lib/discordrb/data/scheduled_event.rb', line 219

def users(limit: 100, member: false)
  get_users = proc do |fetch_limit, after = nil|
    response = JSON.parse(API::Server.get_scheduled_event_users(@bot.token, @server_id, @id, limit: fetch_limit, with_member: member, after: after))
    response.map { |data| data['member'] ? Member.new(data['member'], server, @bot).tap { |member| server&.cache_member(member) } : User.new(data['user'], @bot) }
  end

  # Can be done without pagination.
  return get_users.call(limit) if limit && limit <= 100

  paginator = Paginator.new(limit, :down) do |last_page|
    if last_page && last_page.count < 100
      []
    else
      get_users.call(100, last_page&.last&.id)
    end
  end

  paginator.to_a
end

#voice? ⇒ true, false

Returns whether the scheduled event will take place in a voice channel.

Returns:

  • (true, false) —

    whether the scheduled event will take place in a voice channel.



119
120
121
122
123
 
# File 'lib/discordrb/data/scheduled_event.rb', line 119

ENTITY_TYPES.each do |name, value|
  define_method("#{name}?") do
    @entity_type == value
  end
end