Skip to content

Commit 4890918

Browse files
DV8FromTheWorldcolinloretz
DV8FromTheWorld
and
colinloretz
authored
Documentation for ScheduledEvent.recurrence_rule (#7058)
Co-authored-by: Colin Loretz <[email protected]>
1 parent b73415c commit 4890918

File tree

2 files changed

+182
-8
lines changed

2 files changed

+182
-8
lines changed

‎CONTRIBUTING.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,11 @@ Links between docs can be achieved by using a hash symbol (#), plus the markdown
3939
### Alert Boxes
4040

4141
Alert boxes are created using a block quote that has one of 'warn', 'danger', 'info', or 'preview' on the first line.
42+
For example:
43+
```
44+
> warn
45+
> Something that requires warning here
46+
```
4247

4348
![Alert options](images/alerts.png)
4449

@@ -50,7 +55,12 @@ There are a few reusable MDX components that can be used on pages with the `mdx`
5055

5156
Collapsibles allow you to show/hide content on a page that may be secondary to the page's primary content. They have four fields that can be set: `title`, `description`, `icon`, and an `open` flag (which makes the collapsible element open by default).
5257

53-
Available options for `icon` are `"list"`, `"view"`, `"question"`, and `"code"`.
58+
Available options for `icon`:
59+
- `"list"`
60+
- `"view"`
61+
- `"question"`
62+
- `"code"`
63+
- `"warning"`
5464

5565
###### Example
5666

‎docs/resources/Guild_Scheduled_Event.md‎ renamed to ‎docs/resources/Guild_Scheduled_Event.mdx‎

Lines changed: 171 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ A representation of a scheduled event in a [guild](#DOCS_RESOURCES_GUILD/).
2424
| creator? | [user](#DOCS_RESOURCES_USER/user-object) object | the user that created the scheduled event |
2525
| user_count? | integer | the number of users subscribed to the scheduled event |
2626
| image? | ?string | the [cover image hash](#DOCS_REFERENCE/image-formatting) of the scheduled event |
27+
| recurrence_rule | ?[recurrence rule](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-recurrence-rule-object) | the definition for how often this event should recur |
2728

2829

2930
\* `creator_id` will be null and `creator` will not be included for events created before October 25th, 2021, when the concept of `creator_id` was introduced and tracked.
@@ -101,8 +102,164 @@ SCHEDULED --> CANCELED
101102
| user | [user](#DOCS_RESOURCES_USER/user-object) | user which subscribed to an event |
102103
| member? | [guild member](#DOCS_RESOURCES_GUILD/guild-member-object) | guild member data for this user for the guild which this event belongs to, if any |
103104

104-
105-
## List Scheduled Events for Guild % GET /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/scheduled-events
105+
### Guild Scheduled Event Recurrence Rule Object
106+
Discord's recurrence rule is a subset of the behaviors [defined in the iCalendar RFC](https://datatracker.ietf.org/doc/html/rfc5545) and implemented by [python's dateutil rrule](https://dateutil.readthedocs.io/en/stable/rrule.html)
107+
> warn
108+
> There are currently many limitations to this system. Please see "System limitations" below
109+
110+
###### Guild Scheduled Event Recurrence Rule Structure
111+
112+
| Field | Type | Description |
113+
|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
114+
| start | ISO8601 timestamp | Starting time of the recurrence interval |
115+
| end \[1\] | ?ISO8601 timestamp | Ending time of the recurrence interval |
116+
| frequency | [recurrence rule - frequency](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-recurrence-rule-object-guild-scheduled-event-recurrence-rule-frequency) object | How often the event occurs |
117+
| interval | int | The spacing between the events, defined by `frequency`. For example, `frecency` of `WEEKLY` and an `interval` of `2` would be "every-other week" |
118+
| by_weekday | ?array of [recurrence rule - weekday](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-recurrence-rule-object-guild-scheduled-event-recurrence-rule-weekday) | Set of specific days within a week for the event to recur on |
119+
| by_n_weekday | ?array of [recurrence rule - n_weekday](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-recurrence-rule-object-guild-scheduled-event-recurrence-rule-nweekday-structure) objects | List of specific days within a specific week (1-5) to recur on |
120+
| by_month | ?array of [recurrence rule - month](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-recurrence-rule-object-guild-scheduled-event-recurrence-rule-month) | Set of specific months to recur on |
121+
| by_month_day | ?array of int | Set of specific dates within a month to recur on |
122+
| by_year_day \[1\] | ?array of int | Set of days within a year to recur on (1-364) |
123+
| count \[1\] | ?int | The total amount of times that the event is allowed to recur before stopping |
124+
125+
\[1\] - Cannot be set externally currently.
126+
127+
<Collapsible title="System limitations" description="Recurrence rules are powerful, but they have some specific restrictions" icon="warning">
128+
The current system limitations are present due to how reoccurring event data needs to be displayed in the client.
129+
In the future, we would like to open the system up to have fewer / none of these restrictions.
130+
131+
###### The following fields cannot be set by the client / application
132+
- `count`
133+
- `end`
134+
- `by_year_day`
135+
136+
###### The following combinations are mutually exclusive
137+
- `by_weekday`
138+
- `by_n_weekday`
139+
- `by_month` + `by_month_day`
140+
141+
###### `by_weekday`
142+
- Only valid for daily and weekly events (`frequency` of `DAILY` (`0`) or `WEEKLY` (`1`))
143+
- when used in a daily event (`frequency` is `DAILY` (`0`))
144+
- The values present in the `by_weekday` event must be a "known set" of weekdays.
145+
- The following are current allowed "sets"
146+
- Monday - Friday (`[0, 1, 2, 3, 4]`)
147+
- Tuesday - Saturday (`[1, 2, 3, 4, 5]`)
148+
- Sunday - Thursday (`[6, 0, 1, 2, 3]`)
149+
- Friday & Saturday (`[4, 5]`)
150+
- Saturday & Sunday (`[5, 6]`)
151+
- Sunday & Monday (`[6, 0]`)
152+
- when used in a weekly event (`frequency` is `WEEKLY` (`1`))
153+
- `by_weekday` array currently can only be a length of `1`
154+
- i.e: You can only select a single day within a week to have a recurring event on
155+
- If you wish to have multiple days within a week have a recurring event, please use a `frequency` of `DAILY`
156+
- Also, see `interval` below for "every-other" week information
157+
158+
###### `by_n_weekday`
159+
- Only valid for monthly events (`frequency` of `MONTHLY` (`1`))
160+
- `by_n_weekday` array currently can only be a length of `1`
161+
- i.e: You can only select a single day within a month to have a recurring event on
162+
163+
###### `by_month` and `by_month_day`
164+
- Only valid for annual event (`frequency` is `YEARLY` (`0`))
165+
- both `by_month` and `by_month_day` must be provided
166+
- both `by_month` and `by_month_day` arrays must have a length of `1`
167+
- (i.e: You can only set a single date for annual events)
168+
169+
###### `interval` can only be set to a value other than `1` when `frequency` is set to `WEEKLY` (`1`)
170+
- In this situation, interval can be set to `2`
171+
- This allowance enables "every-other week" events
172+
- Due to the limitations placed on `by_weekday` this means that if you wish to use "every-other week" functionality
173+
you can only do so for a single day.
174+
</Collapsible>
175+
176+
<Collapsible title="Examples" description="Simple examples of some common Recurrent Rules" icon="list">
177+
**Every weekday**
178+
```js
179+
frequency = 3 // Frequency.DAILY
180+
interval = 1
181+
by_weekday = [0, 1, 2, 3, 4] // [Weekday.MONDAY, ..., Weekday.FRIDAY]
182+
```
183+
184+
**Every Wednesday**
185+
```js
186+
frequency = 2 // Frequency.WEEKLY
187+
interval = 1
188+
by_weekday = [2] // [Weekday.WEDNESDAY]
189+
```
190+
191+
**Every other Wednesday**
192+
```js
193+
frequency = 2 // Frequency.WEEKLY
194+
interval = 2
195+
by_weekday = [2] // [Weekday.WEDNESDAY]
196+
```
197+
198+
**Monthly on the fourth Wednesday**
199+
```js
200+
frequency = 1 // Frequency.MONTHLY
201+
interval = 1
202+
by_n_weekday = [{
203+
n: 4,
204+
day: 2 // Weekday.WEDNESDAY
205+
}]
206+
```
207+
208+
**Annually on July 24**
209+
```js
210+
frequency = 0 // Frequency.YEARLY
211+
interval = 1
212+
by_month = [7] // [Month.JULY]
213+
by_month_day = [24]
214+
```
215+
</Collapsible>
216+
217+
###### Guild Scheduled Event Recurrence Rule - Frequency
218+
219+
| Type | Value |
220+
|---------|-------|
221+
| YEARLY | 0 |
222+
| MONTHLY | 1 |
223+
| WEEKLY | 2 |
224+
| DAILY | 3 |
225+
226+
###### Guild Scheduled Event Recurrence Rule - Weekday
227+
228+
| Type | Value |
229+
|-----------|-------|
230+
| MONDAY | 0 |
231+
| TUESDAY | 1 |
232+
| WEDNESDAY | 2 |
233+
| THURSDAY | 3 |
234+
| FRIDAY | 4 |
235+
| SATURDAY | 5 |
236+
| SUNDAY | 6 |
237+
238+
###### Guild Scheduled Event Recurrence Rule - N_Weekday Structure
239+
240+
| Field | Type | Description |
241+
|-------|------|-------------------------------|
242+
| n | int | The week to reoccur on. 1 - 5 |
243+
| day | [recurrence rule - weekday](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-recurrence-rule-object-guild-scheduled-event-recurrence-rule-weekday) | The day within the week to reoccur on | | guild member data for this user for the guild which this event belongs to, if any |
244+
245+
###### Guild Scheduled Event Recurrence Rule - Month
246+
247+
| Type | Value |
248+
|-----------|-------|
249+
| JANUARY | 1 |
250+
| FEBRUARY | 2 |
251+
| MARCH | 3 |
252+
| APRIL | 4 |
253+
| MAY | 5 |
254+
| JUNE | 6 |
255+
| JULY | 7 |
256+
| AUGUST | 8 |
257+
| SEPTEMBER | 9 |
258+
| OCTOBER | 10 |
259+
| NOVEMBER | 11 |
260+
| DECEMBER | 12 |
261+
262+
## List Scheduled Events for Guild % GET /guilds/\{guild.id#DOCS_RESOURCES_GUILD/guild-object\}/scheduled-events
106263

107264
Returns a list of [guild scheduled event](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object) objects for the given guild.
108265

@@ -112,7 +269,7 @@ Returns a list of [guild scheduled event](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/
112269
|------------------|--------------------------------------------------|--------------------------------------------------|
113270
| with_user_count? | [boolean](#DOCS_REFERENCE/boolean-query-strings) | include number of users subscribed to each event |
114271

115-
## Create Guild Scheduled Event % POST /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/scheduled-events
272+
## Create Guild Scheduled Event % POST /guilds/\{guild.id#DOCS_RESOURCES_GUILD/guild-object\}/scheduled-events
116273

117274
Create a guild scheduled event in the guild. Returns a [guild scheduled event](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object) object on success. Fires a [Guild Scheduled Event Create](#DOCS_TOPICS_GATEWAY_EVENTS/guild-scheduled-event-create) Gateway event.
118275

@@ -135,12 +292,14 @@ Create a guild scheduled event in the guild. Returns a [guild scheduled event](#
135292
| description? | string | the description of the scheduled event |
136293
| entity_type | [entity type](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object-guild-scheduled-event-entity-types) | the entity type of the scheduled event |
137294
| image? | [image data](#DOCS_REFERENCE/image-data) | the cover image of the scheduled event |
295+
| recurrence_rule? | [recurrence rule](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-recurrence-rule-object) | the definition for how often this event should recur |
296+
138297

139298
\* Optional for events with `'entity_type': EXTERNAL`
140299

141300
\*\* Required for events with `'entity_type': EXTERNAL`
142301

143-
## Get Guild Scheduled Event % GET /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/scheduled-events/{guild_scheduled_event.id#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object}
302+
## Get Guild Scheduled Event % GET /guilds/\{guild.id#DOCS_RESOURCES_GUILD/guild-object\}/scheduled-events/\{guild_scheduled_event.id#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object\}
144303

145304
Get a guild scheduled event. Returns a [guild scheduled event](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object) object on success.
146305

@@ -150,7 +309,7 @@ Get a guild scheduled event. Returns a [guild scheduled event](#DOCS_RESOURCES_G
150309
|------------------|--------------------------------------------------|--------------------------------------------------|
151310
| with_user_count? | [boolean](#DOCS_REFERENCE/boolean-query-strings) | include number of users subscribed to this event |
152311

153-
## Modify Guild Scheduled Event % PATCH /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/scheduled-events/{guild_scheduled_event.id#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object}
312+
## Modify Guild Scheduled Event % PATCH /guilds/\{guild.id#DOCS_RESOURCES_GUILD/guild-object\}/scheduled-events/\{guild_scheduled_event.id#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object\}
154313

155314
Modify a guild scheduled event. Returns the modified [guild scheduled event](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object) object on success. Fires a [Guild Scheduled Event Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-scheduled-event-update) Gateway event.
156315

@@ -163,6 +322,9 @@ Modify a guild scheduled event. Returns the modified [guild scheduled event](#DO
163322
> info
164323
> This endpoint silently discards `entity_metadata` for non-`EXTERNAL` events.
165324
325+
> info
326+
> All parameters to this endpoint are optional
327+
166328
###### JSON Params
167329

168330
| Field | Type | Description |
@@ -177,18 +339,20 @@ Modify a guild scheduled event. Returns the modified [guild scheduled event](#DO
177339
| entity_type? * | [event entity type](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object-guild-scheduled-event-entity-types) | the entity type of the scheduled event |
178340
| status? | [event status](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object-guild-scheduled-event-status) | the status of the scheduled event |
179341
| image? | [image data](#DOCS_REFERENCE/image-data) | the cover image of the scheduled event |
342+
| recurrence_rule? | [recurrence rule](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-recurrence-rule-object) | the definition for how often this event should recur |
343+
180344

181345
\* If updating `entity_type` to `EXTERNAL`:
182346

183347
- `channel_id` is required and [must be set to null](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object-field-requirements-by-entity-type)
184348
- `entity_metadata` with a `location` field must be provided
185349
- `scheduled_end_time` must be provided
186350

187-
## Delete Guild Scheduled Event % DELETE /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/scheduled-events/{guild_scheduled_event.id#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object}
351+
## Delete Guild Scheduled Event % DELETE /guilds/\{guild.id#DOCS_RESOURCES_GUILD/guild-object\}/scheduled-events/\{guild_scheduled_event.id#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object\}
188352

189353
Delete a guild scheduled event. Returns a `204` on success. Fires a [Guild Scheduled Event Delete](#DOCS_TOPICS_GATEWAY_EVENTS/guild-scheduled-event-delete) Gateway event.
190354

191-
## Get Guild Scheduled Event Users % GET /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/scheduled-events/{guild_scheduled_event.id#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object}/users
355+
## Get Guild Scheduled Event Users % GET /guilds/\{guild.id#DOCS_RESOURCES_GUILD/guild-object\}/scheduled-events/\{guild_scheduled_event.id#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object\}/users
192356

193357
Get a list of guild scheduled event users subscribed to a guild scheduled event. Returns a list of [guild scheduled event user](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-user-object) objects on success. Guild member data, if it exists, is included if the `with_member` query parameter is set.
194358

0 commit comments

Comments
 (0)