feat(APIGuildScheduledEvent): add more precise types for stage instance/voice/external events (#278)

This commit turns `APIGuildScheduledEvent` into a union of
`APIStageInstanceGuildScheduledEvent`, `APIVoiceGuildScheduledEvent`,
and `APIExternalGuildScheduledEvent`, which each has more precise types
according to [the docs][1].

This commit also fixes a bug as previously
`APIGuildScheduledEvent#entity_metadata` was not nullable, even though
it should be.

[1]: https://discord.com/developers/docs/resources/guild-scheduled-event#guild-scheduled-event-object-field-requirements-by-entity-type

Author: cherryblossom000

deno/payloads/v8/guildScheduledEvent.ts

@@ -2,7 +2,7 @@ import type { APIUser } from './user.ts';
 import type { APIGuildMember } from './guild.ts';
 import type { Snowflake } from '../../globals.ts';
 
-export interface APIGuildScheduledEvent {
+interface APIGuildScheduledEventBase<Type extends GuildScheduledEventEntityType> {
 	/**
 	 * The id of the guild event
 	 */
@@ -46,15 +46,15 @@ export interface APIGuildScheduledEvent {
 	/**
 	 * The type of hosting entity associated with the scheduled event
 	 */
-	entity_type: GuildScheduledEventEntityType;
+	entity_type: Type;
 	/**
 	 * The id of the hosting entity associated with the scheduled event
 	 */
 	entity_id: Snowflake | null;
 	/**
 	 * The entity metadata for the scheduled event
 	 */
-	entity_metadata: APIGuildScheduledEventEntityMetadata;
+	entity_metadata: APIGuildScheduledEventEntityMetadata | null;
 	/**
 	 * The user that created the scheduled event
 	 */
@@ -65,6 +65,31 @@ export interface APIGuildScheduledEvent {
 	user_count?: number;
 }
 
+export interface APIStageInstanceGuildScheduledEvent
+	extends APIGuildScheduledEventBase<GuildScheduledEventEntityType.StageInstance> {
+	channel_id: Snowflake;
+	entity_metadata: null;
+}
+
+export interface APIVoiceGuildScheduledEvent extends APIGuildScheduledEventBase<GuildScheduledEventEntityType.Voice> {
+	channel_id: Snowflake;
+	entity_metadata: null;
+}
+
+export interface APIExternalGuildScheduledEvent
+	extends APIGuildScheduledEventBase<GuildScheduledEventEntityType.External> {
+	channel_id: null;
+	entity_metadata: Required<APIGuildScheduledEventEntityMetadata>;
+}
+
+/**
+ * https://discord.com/developers/docs/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-structure
+ */
+export type APIGuildScheduledEvent =
+	| APIStageInstanceGuildScheduledEvent
+	| APIVoiceGuildScheduledEvent
+	| APIExternalGuildScheduledEvent;
+
 /**
  * https://discord.com/developers/docs/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-entity-metadata
  */

deno/payloads/v9/guildScheduledEvent.ts

@@ -2,7 +2,7 @@ import type { APIUser } from './user.ts';
 import type { APIGuildMember } from './guild.ts';
 import type { Snowflake } from '../../globals.ts';
 
-export interface APIGuildScheduledEvent {
+interface APIGuildScheduledEventBase<Type extends GuildScheduledEventEntityType> {
 	/**
 	 * The id of the guild event
 	 */
@@ -46,15 +46,15 @@ export interface APIGuildScheduledEvent {
 	/**
 	 * The type of hosting entity associated with the scheduled event
 	 */
-	entity_type: GuildScheduledEventEntityType;
+	entity_type: Type;
 	/**
 	 * The id of the hosting entity associated with the scheduled event
 	 */
 	entity_id: Snowflake | null;
 	/**
 	 * The entity metadata for the scheduled event
 	 */
-	entity_metadata: APIGuildScheduledEventEntityMetadata;
+	entity_metadata: APIGuildScheduledEventEntityMetadata | null;
 	/**
 	 * The user that created the scheduled event
 	 */
@@ -65,6 +65,31 @@ export interface APIGuildScheduledEvent {
 	user_count?: number;
 }
 
+export interface APIStageInstanceGuildScheduledEvent
+	extends APIGuildScheduledEventBase<GuildScheduledEventEntityType.StageInstance> {
+	channel_id: Snowflake;
+	entity_metadata: null;
+}
+
+export interface APIVoiceGuildScheduledEvent extends APIGuildScheduledEventBase<GuildScheduledEventEntityType.Voice> {
+	channel_id: Snowflake;
+	entity_metadata: null;
+}
+
+export interface APIExternalGuildScheduledEvent
+	extends APIGuildScheduledEventBase<GuildScheduledEventEntityType.External> {
+	channel_id: null;
+	entity_metadata: Required<APIGuildScheduledEventEntityMetadata>;
+}
+
+/**
+ * https://discord.com/developers/docs/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-structure
+ */
+export type APIGuildScheduledEvent =
+	| APIStageInstanceGuildScheduledEvent
+	| APIVoiceGuildScheduledEvent
+	| APIExternalGuildScheduledEvent;
+
 /**
  * https://discord.com/developers/docs/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-entity-metadata
  */

payloads/v8/guildScheduledEvent.ts

@@ -2,7 +2,7 @@ import type { APIUser } from './user';
 import type { APIGuildMember } from './guild';
 import type { Snowflake } from '../../globals';
 
-export interface APIGuildScheduledEvent {
+interface APIGuildScheduledEventBase<Type extends GuildScheduledEventEntityType> {
 	/**
 	 * The id of the guild event
 	 */
@@ -46,15 +46,15 @@ export interface APIGuildScheduledEvent {
 	/**
 	 * The type of hosting entity associated with the scheduled event
 	 */
-	entity_type: GuildScheduledEventEntityType;
+	entity_type: Type;
 	/**
 	 * The id of the hosting entity associated with the scheduled event
 	 */
 	entity_id: Snowflake | null;
 	/**
 	 * The entity metadata for the scheduled event
 	 */
-	entity_metadata: APIGuildScheduledEventEntityMetadata;
+	entity_metadata: APIGuildScheduledEventEntityMetadata | null;
 	/**
 	 * The user that created the scheduled event
 	 */
@@ -65,6 +65,31 @@ export interface APIGuildScheduledEvent {
 	user_count?: number;
 }
 
+export interface APIStageInstanceGuildScheduledEvent
+	extends APIGuildScheduledEventBase<GuildScheduledEventEntityType.StageInstance> {
+	channel_id: Snowflake;
+	entity_metadata: null;
+}
+
+export interface APIVoiceGuildScheduledEvent extends APIGuildScheduledEventBase<GuildScheduledEventEntityType.Voice> {
+	channel_id: Snowflake;
+	entity_metadata: null;
+}
+
+export interface APIExternalGuildScheduledEvent
+	extends APIGuildScheduledEventBase<GuildScheduledEventEntityType.External> {
+	channel_id: null;
+	entity_metadata: Required<APIGuildScheduledEventEntityMetadata>;
+}
+
+/**
+ * https://discord.com/developers/docs/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-structure
+ */
+export type APIGuildScheduledEvent =
+	| APIStageInstanceGuildScheduledEvent
+	| APIVoiceGuildScheduledEvent
+	| APIExternalGuildScheduledEvent;
+
 /**
  * https://discord.com/developers/docs/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-entity-metadata
  */

payloads/v9/guildScheduledEvent.ts

@@ -2,7 +2,7 @@ import type { APIUser } from './user';
 import type { APIGuildMember } from './guild';
 import type { Snowflake } from '../../globals';
 
-export interface APIGuildScheduledEvent {
+interface APIGuildScheduledEventBase<Type extends GuildScheduledEventEntityType> {
 	/**
 	 * The id of the guild event
 	 */
@@ -46,15 +46,15 @@ export interface APIGuildScheduledEvent {
 	/**
 	 * The type of hosting entity associated with the scheduled event
 	 */
-	entity_type: GuildScheduledEventEntityType;
+	entity_type: Type;
 	/**
 	 * The id of the hosting entity associated with the scheduled event
 	 */
 	entity_id: Snowflake | null;
 	/**
 	 * The entity metadata for the scheduled event
 	 */
-	entity_metadata: APIGuildScheduledEventEntityMetadata;
+	entity_metadata: APIGuildScheduledEventEntityMetadata | null;
 	/**
 	 * The user that created the scheduled event
 	 */
@@ -65,6 +65,31 @@ export interface APIGuildScheduledEvent {
 	user_count?: number;
 }
 
+export interface APIStageInstanceGuildScheduledEvent
+	extends APIGuildScheduledEventBase<GuildScheduledEventEntityType.StageInstance> {
+	channel_id: Snowflake;
+	entity_metadata: null;
+}
+
+export interface APIVoiceGuildScheduledEvent extends APIGuildScheduledEventBase<GuildScheduledEventEntityType.Voice> {
+	channel_id: Snowflake;
+	entity_metadata: null;
+}
+
+export interface APIExternalGuildScheduledEvent
+	extends APIGuildScheduledEventBase<GuildScheduledEventEntityType.External> {
+	channel_id: null;
+	entity_metadata: Required<APIGuildScheduledEventEntityMetadata>;
+}
+
+/**
+ * https://discord.com/developers/docs/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-structure
+ */
+export type APIGuildScheduledEvent =
+	| APIStageInstanceGuildScheduledEvent
+	| APIVoiceGuildScheduledEvent
+	| APIExternalGuildScheduledEvent;
+
 /**
  * https://discord.com/developers/docs/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-entity-metadata
  */