types: Add tagged type unions for channel types (#200)

BREAKING CHANGE: All of the channel types are now split based on their type. As such, you will need to assert the type (either by checking it with the enum or by casting the data as the correct channel) before accessing data.
*If you encounter any missing properties due to this, please open an issue! This is a big change, and we hope nothing is missing*

Co-authored-by: Vlad Frangu <kingdgrizzle@gmail.com>
Co-authored-by: Antonio Román <kyradiscord@gmail.com>

.gitignore

@@ -45,3 +45,6 @@ voice/**/*.js
 voice/**/*.map
 voice/**/*.d.ts
 voice/**/*.mjs
+
+# macOS files
+.DS_store

deno/payloads/v8/channel.ts

@@ -32,17 +32,37 @@ export interface APIPartialChannel {
 }
 
 /**
- * https://discord.com/developers/docs/resources/channel#channel-object-channel-structure
+ * This interface is used to allow easy extension for other channel types. While
+ * also allowing `APIPartialChannel` to be used without breaking.
  */
-export interface APIChannel extends APIPartialChannel {
+export interface APIChannelBase<T extends ChannelType> extends APIPartialChannel {
+	type: T;
+}
+
+// TODO: update when text in voice is released
+export type TextChannelType = ChannelType.DM | ChannelType.GroupDM | ChannelType.GuildNews | ChannelType.GuildText;
+
+export type GuildChannelType = Exclude<
+	| TextChannelType
+	| ChannelType.GuildVoice
+	| ChannelType.GuildStageVoice
+	| ChannelType.GuildNews
+	| ChannelType.GuildStore,
+	ChannelType.DM | ChannelType.GroupDM
+>;
+
+export interface APITextBasedChannel<T extends ChannelType> extends APIChannelBase<T> {
+	/**
+	 * The id of the last message sent in this channel (may not point to an existing or valid message)
+	 */
+	last_message_id?: Snowflake | null;
+}
+
+export interface APIGuildChannel<T extends ChannelType> extends APIChannelBase<T> {
 	/**
 	 * The id of the guild (may be missing for some channel objects received over gateway guild dispatches)
 	 */
 	guild_id?: Snowflake;
-	/**
-	 * Sorting position of the channel
-	 */
-	position?: number;
 	/**
 	 * Explicit permission overwrites for members and roles
 	 *
@@ -50,17 +70,48 @@ export interface APIChannel extends APIPartialChannel {
 	 */
 	permission_overwrites?: APIOverwrite[];
 	/**
-	 * The channel topic (0-1024 characters)
+	 * Sorting position of the channel
 	 */
-	topic?: string | null;
+	position?: number;
+	/**
+	 * ID of the parent category for a channel (each parent category can contain up to 50 channels)
+	 */
+	parent_id?: Snowflake | null;
 	/**
 	 * Whether the channel is nsfw
 	 */
 	nsfw?: boolean;
+}
+
+export type GuildTextChannelType = Exclude<TextChannelType, ChannelType.DM | ChannelType.GroupDM>;
+
+export interface APIGuildTextChannel<T extends GuildTextChannelType>
+	extends APITextBasedChannel<T>,
+		APIGuildChannel<T> {
 	/**
-	 * The id of the last message sent in this channel (may not point to an existing or valid message)
+	 * The channel topic (0-1024 characters)
 	 */
-	last_message_id?: Snowflake | null;
+	topic?: string | null;
+	/**
+	 * When the last pinned message was pinned.
+	 * This may be `null` in events such as `GUILD_CREATE` when a message is not pinned
+	 */
+	last_pin_timestamp?: string | null;
+}
+
+export interface APITextChannel extends APIGuildTextChannel<ChannelType.GuildText> {
+	/**
+	 * Amount of seconds a user has to wait before sending another message (0-21600);
+	 * bots, as well as users with the permission `MANAGE_MESSAGES` or `MANAGE_CHANNELS`, are unaffected
+	 */
+	rate_limit_per_user?: number;
+}
+
+export type APINewsChannel = APIGuildTextChannel<ChannelType.GuildNews>;
+export type APIGuildCategoryChannel = APIGuildChannel<ChannelType.GuildCategory>;
+export type APIGuildStoreChannel = APIGuildChannel<ChannelType.GuildStore>;
+
+export interface APIVoiceChannel extends APIGuildChannel<ChannelType.GuildStageVoice | ChannelType.GuildVoice> {
 	/**
 	 * The bitrate (in bits) of the voice channel
 	 */
@@ -69,38 +120,6 @@ export interface APIChannel extends APIPartialChannel {
 	 * The user limit of the voice channel
 	 */
 	user_limit?: number;
-	/**
-	 * Amount of seconds a user has to wait before sending another message (0-21600);
-	 * bots, as well as users with the permission `MANAGE_MESSAGES` or `MANAGE_CHANNELS`, are unaffected
-	 */
-	rate_limit_per_user?: number;
-	/**
-	 * The recipients of the DM
-	 *
-	 * See https://discord.com/developers/docs/resources/user#user-object
-	 */
-	recipients?: APIUser[];
-	/**
-	 * Icon hash
-	 */
-	icon?: string | null;
-	/**
-	 * ID of the DM creator
-	 */
-	owner_id?: Snowflake;
-	/**
-	 * Application id of the group DM creator if it is bot-created
-	 */
-	application_id?: Snowflake;
-	/**
-	 * ID of the parent category for a channel (each parent category can contain up to 50 channels)
-	 */
-	parent_id?: Snowflake | null;
-	/**
-	 * When the last pinned message was pinned.
-	 * This may be `null` in events such as `GUILD_CREATE` when a message is not pinned
-	 */
-	last_pin_timestamp?: string | null;
 	/**
 	 * Voice region id for the voice or stage channel, automatic when set to `null`
 	 *
@@ -115,6 +134,49 @@ export interface APIChannel extends APIPartialChannel {
 	video_quality_mode?: VideoQualityMode;
 }
 
+interface APIDMChannelBase<T extends ChannelType> extends APITextBasedChannel<T> {
+	/**
+	 * The recipients of the DM
+	 *
+	 * See https://discord.com/developers/docs/resources/user#user-object
+	 */
+	recipients?: APIUser[];
+}
+
+export type APIDMChannel = APIDMChannelBase<ChannelType.DM>;
+
+export interface APIGroupDMChannel extends APIDMChannelBase<ChannelType.GroupDM> {
+	/**
+	 * Application id of the group DM creator if it is bot-created
+	 */
+	application_id?: Snowflake;
+	/**
+	 * Icon hash
+	 */
+	icon?: string | null;
+	/**
+	 * ID of the DM creator
+	 */
+	owner_id?: Snowflake;
+	/**
+	 * The id of the last message sent in this channel (may not point to an existing or valid message)
+	 */
+	last_message_id?: Snowflake | null;
+}
+
+/**
+ * https://discord.com/developers/docs/resources/channel#channel-object-channel-structure
+ */
+export type APIChannel =
+	| APIGroupDMChannel
+	| APIDMChannel
+	| APITextChannel
+	| APINewsChannel
+	| APIGuildStoreChannel
+	| APIVoiceChannel
+	| APIGuildCategoryChannel
+	| APINewsChannel;
+
 /**
  * https://discord.com/developers/docs/resources/channel#channel-object-channel-types
  */

deno/payloads/v9/channel.ts

@@ -32,17 +32,44 @@ export interface APIPartialChannel {
 }
 
 /**
- * https://discord.com/developers/docs/resources/channel#channel-object-channel-structure
+ * This interface is used to allow easy extension for other channel types. While
+ * also allowing `APIPartialChannel` to be used without breaking.
  */
-export interface APIChannel extends APIPartialChannel {
+export interface APIChannelBase<T extends ChannelType> extends APIPartialChannel {
+	type: T;
+}
+
+// TODO: update when text in voice is released
+export type TextChannelType =
+	| ChannelType.DM
+	| ChannelType.GroupDM
+	| ChannelType.GuildNews
+	| ChannelType.GuildPublicThread
+	| ChannelType.GuildPrivateThread
+	| ChannelType.GuildNewsThread
+	| ChannelType.GuildText;
+
+export type GuildChannelType = Exclude<
+	| TextChannelType
+	| ChannelType.GuildVoice
+	| ChannelType.GuildStageVoice
+	| ChannelType.GuildNews
+	| ChannelType.GuildStore,
+	ChannelType.DM | ChannelType.GroupDM
+>;
+
+export interface APITextBasedChannel<T extends ChannelType> extends APIChannelBase<T> {
+	/**
+	 * The id of the last message sent in this channel (may not point to an existing or valid message)
+	 */
+	last_message_id?: Snowflake | null;
+}
+
+export interface APIGuildChannel<T extends ChannelType> extends APIChannelBase<T> {
 	/**
 	 * The id of the guild (may be missing for some channel objects received over gateway guild dispatches)
 	 */
 	guild_id?: Snowflake;
-	/**
-	 * Sorting position of the channel
-	 */
-	position?: number;
 	/**
 	 * Explicit permission overwrites for members and roles
 	 *
@@ -50,25 +77,44 @@ export interface APIChannel extends APIPartialChannel {
 	 */
 	permission_overwrites?: APIOverwrite[];
 	/**
-	 * The channel topic (0-1024 characters)
+	 * Sorting position of the channel
 	 */
-	topic?: string | null;
+	position?: number;
+	/**
+	 * ID of the parent category for a channel (each parent category can contain up to 50 channels)
+	 *
+	 * OR
+	 *
+	 * ID of the parent channel for a thread
+	 */
+	parent_id?: Snowflake | null;
 	/**
 	 * Whether the channel is nsfw
 	 */
 	nsfw?: boolean;
+}
+
+export type GuildTextChannelType = Exclude<TextChannelType, ChannelType.DM | ChannelType.GroupDM>;
+
+export interface APIGuildTextChannel<T extends GuildTextChannelType>
+	extends APITextBasedChannel<T>,
+		APIGuildChannel<T> {
 	/**
-	 * The id of the last message sent in this channel (may not point to an existing or valid message)
+	 * Default duration for newly created threads, in minutes, to automatically archive the thread after recent activity
 	 */
-	last_message_id?: Snowflake | null;
+	default_auto_archive_duration?: ThreadAutoArchiveDuration;
 	/**
-	 * The bitrate (in bits) of the voice channel
+	 * The channel topic (0-1024 characters)
 	 */
-	bitrate?: number;
+	topic?: string | null;
 	/**
-	 * The user limit of the voice channel
+	 * When the last pinned message was pinned.
+	 * This may be `null` in events such as `GUILD_CREATE` when a message is not pinned
 	 */
-	user_limit?: number;
+	last_pin_timestamp?: string | null;
+}
+
+export interface APITextChannel extends APIGuildTextChannel<ChannelType.GuildText> {
 	/**
 	 * Amount of seconds a user has to wait before sending another message (0-21600);
 	 * bots, as well as users with the permission `MANAGE_MESSAGES` or `MANAGE_CHANNELS`, are unaffected
@@ -79,37 +125,21 @@ export interface APIChannel extends APIPartialChannel {
 	 * The absence of this field in API calls and Gateway events should indicate that slowmode has been reset to the default value.
 	 */
 	rate_limit_per_user?: number;
+}
+
+export type APINewsChannel = APIGuildTextChannel<ChannelType.GuildNews>;
+export type APIGuildCategoryChannel = APIGuildChannel<ChannelType.GuildCategory>;
+export type APIGuildStoreChannel = APIGuildChannel<ChannelType.GuildStore>;
+
+export interface APIVoiceChannel extends APIGuildChannel<ChannelType.GuildStageVoice | ChannelType.GuildVoice> {
 	/**
-	 * The recipients of the DM
-	 *
-	 * See https://discord.com/developers/docs/resources/user#user-object
+	 * The bitrate (in bits) of the voice channel
 	 */
-	recipients?: APIUser[];
+	bitrate?: number;
 	/**
-	 * Icon hash
+	 * The user limit of the voice channel
 	 */
-	icon?: string | null;
-	/**
-	 * ID of the DM creator or thread creator
-	 */
-	owner_id?: Snowflake;
-	/**
-	 * Application id of the group DM creator if it is bot-created
-	 */
-	application_id?: Snowflake;
-	/**
-	 * ID of the parent category for a channel (each parent category can contain up to 50 channels)
-	 *
-	 * OR
-	 *
-	 * ID of the parent channel for a thread
-	 */
-	parent_id?: Snowflake | null;
-	/**
-	 * When the last pinned message was pinned.
-	 * This may be `null` in events such as `GUILD_CREATE` when a message is not pinned
-	 */
-	last_pin_timestamp?: string | null;
+	user_limit?: number;
 	/**
 	 * Voice region id for the voice or stage channel, automatic when set to `null`
 	 *
@@ -122,6 +152,50 @@ export interface APIChannel extends APIPartialChannel {
 	 * See https://discord.com/developers/docs/resources/channel#channel-object-video-quality-modes
 	 */
 	video_quality_mode?: VideoQualityMode;
+}
+
+interface APIDMChannelBase<T extends ChannelType> extends APITextBasedChannel<T> {
+	/**
+	 * The recipients of the DM
+	 *
+	 * See https://discord.com/developers/docs/resources/user#user-object
+	 */
+	recipients?: APIUser[];
+}
+
+export type APIDMChannel = APIDMChannelBase<ChannelType.DM>;
+
+export interface APIGroupDMChannel extends APIDMChannelBase<ChannelType.GroupDM> {
+	/**
+	 * Application id of the group DM creator if it is bot-created
+	 */
+	application_id?: Snowflake;
+	/**
+	 * Icon hash
+	 */
+	icon?: string | null;
+	/**
+	 * ID of the DM creator
+	 */
+	owner_id?: Snowflake;
+	/**
+	 * The id of the last message sent in this channel (may not point to an existing or valid message)
+	 */
+	last_message_id?: Snowflake | null;
+}
+
+export interface APIThreadChannel
+	extends APIGuildChannel<
+		ChannelType.GuildPublicThread | ChannelType.GuildPrivateThread | ChannelType.GuildNewsThread
+	> {
+	/**
+	 * The client users member for the thread, only included in select endpoints
+	 */
+	member?: APIThreadMember;
+	/**
+	 * The metadata for a thread channel not shared by other channels
+	 */
+	thread_metadata?: APIThreadMetadata;
 	/**
 	 * The approximate message count of the thread, does not count above 50 even if there are more messages
 	 */
@@ -131,19 +205,39 @@ export interface APIChannel extends APIPartialChannel {
 	 */
 	member_count?: number;
 	/**
-	 * The metadata for a thread channel not shared by other channels
+	 * Amount of seconds a user has to wait before sending another message (0-21600);
+	 * bots, as well as users with the permission `MANAGE_MESSAGES` or `MANAGE_CHANNELS`, are unaffected
+	 *
+	 * `rate_limit_per_user` also applies to thread creation. Users can send one message and create one thread during each `rate_limit_per_user` interval.
+	 *
+	 * For thread channels, `rate_limit_per_user` is only returned if the field is set to a non-zero and non-null value.
+	 * The absence of this field in API calls and Gateway events should indicate that slowmode has been reset to the default value.
 	 */
-	thread_metadata?: APIThreadMetadata;
+	rate_limit_per_user?: number;
 	/**
-	 * The client users member for the thread, only included in select endpoints
+	 * ID of the thread creator
 	 */
-	member?: APIThreadMember;
+	owner_id?: Snowflake;
 	/**
-	 * Default duration for newly created threads, in minutes, to automatically archive the thread after recent activity
+	 * The id of the last message sent in this thread (may not point to an existing or valid message)
 	 */
-	default_auto_archive_duration?: ThreadAutoArchiveDuration;
+	last_message_id?: Snowflake | null;
 }
 
+/**
+ * https://discord.com/developers/docs/resources/channel#channel-object-channel-structure
+ */
+export type APIChannel =
+	| APIGroupDMChannel
+	| APIDMChannel
+	| APITextChannel
+	| APINewsChannel
+	| APIGuildStoreChannel
+	| APIVoiceChannel
+	| APIGuildCategoryChannel
+	| APIThreadChannel
+	| APINewsChannel;
+
 /**
  * https://discord.com/developers/docs/resources/channel#channel-object-channel-types
  */

deno/rest/v8/guild.ts

@@ -2,7 +2,9 @@ import type { Permissions, Snowflake } from '../../globals.ts';
 import type {
 	APIBan,
 	APIChannel,
+	APIDMChannel,
 	APIExtendedInvite,
+	APIGroupDMChannel,
 	APIGuild,
 	APIGuildIntegration,
 	APIGuildMember,
@@ -25,6 +27,7 @@ import type {
 	Nullable,
 	StrictPartial,
 	StrictRequired,
+	UnionToIntersection,
 } from '../../utils/internals.ts';
 import type { RESTPutAPIChannelPermissionJSONBody } from './channel.ts';
 
@@ -32,8 +35,12 @@ export interface APIGuildCreateOverwrite extends RESTPutAPIChannelPermissionJSON
 	id: number | string;
 }
 
+export type APIGuildChannelResolvable = Exclude<APIChannel, APIDMChannel | APIGroupDMChannel>;
 export type APIGuildCreatePartialChannel = StrictPartial<
-	Pick<APIChannel, 'type' | 'topic' | 'nsfw' | 'bitrate' | 'user_limit' | 'rate_limit_per_user'>
+	Pick<
+		UnionToIntersection<APIGuildChannelResolvable>,
+		'type' | 'topic' | 'nsfw' | 'bitrate' | 'user_limit' | 'rate_limit_per_user'
+	>
 > &
 	AddUndefinedToPossiblyUndefinedPropertiesOfInterface<{
 		name: string;

deno/rest/v9/guild.ts

@@ -20,12 +20,15 @@ import type {
 	GuildSystemChannelFlags,
 	GuildVerificationLevel,
 	GuildWidgetStyle,
+	APIDMChannel,
+	APIGroupDMChannel,
 } from '../../payloads/v9/mod.ts';
 import type {
 	AddUndefinedToPossiblyUndefinedPropertiesOfInterface,
 	Nullable,
 	StrictPartial,
 	StrictRequired,
+	UnionToIntersection,
 } from '../../utils/internals.ts';
 import type { RESTPutAPIChannelPermissionJSONBody } from './channel.ts';
 
@@ -33,8 +36,12 @@ export interface APIGuildCreateOverwrite extends RESTPutAPIChannelPermissionJSON
 	id: number | string;
 }
 
+export type APIGuildChannelResolvable = Exclude<APIChannel, APIDMChannel | APIGroupDMChannel>;
 export type APIGuildCreatePartialChannel = StrictPartial<
-	Pick<APIChannel, 'type' | 'topic' | 'nsfw' | 'bitrate' | 'user_limit' | 'rate_limit_per_user'>
+	Pick<
+		UnionToIntersection<APIGuildChannelResolvable>,
+		'type' | 'topic' | 'nsfw' | 'bitrate' | 'user_limit' | 'rate_limit_per_user'
+	>
 > &
 	AddUndefinedToPossiblyUndefinedPropertiesOfInterface<{
 		name: string;

deno/utils/internals.ts

@@ -13,3 +13,5 @@ export type AddUndefinedToPossiblyUndefinedPropertiesOfInterface<Base> = {
 export type StrictPartial<Base> = AddUndefinedToPossiblyUndefinedPropertiesOfInterface<Partial<Base>>;
 
 export type StrictRequired<Base> = Required<{ [K in keyof Base]: Exclude<Base[K], undefined> }>;
+
+export type UnionToIntersection<T> = (T extends any ? (x: T) => any : never) extends (x: infer R) => any ? R : never;

payloads/v8/channel.ts

@@ -32,17 +32,37 @@ export interface APIPartialChannel {
 }
 
 /**
- * https://discord.com/developers/docs/resources/channel#channel-object-channel-structure
+ * This interface is used to allow easy extension for other channel types. While
+ * also allowing `APIPartialChannel` to be used without breaking.
  */
-export interface APIChannel extends APIPartialChannel {
+export interface APIChannelBase<T extends ChannelType> extends APIPartialChannel {
+	type: T;
+}
+
+// TODO: update when text in voice is released
+export type TextChannelType = ChannelType.DM | ChannelType.GroupDM | ChannelType.GuildNews | ChannelType.GuildText;
+
+export type GuildChannelType = Exclude<
+	| TextChannelType
+	| ChannelType.GuildVoice
+	| ChannelType.GuildStageVoice
+	| ChannelType.GuildNews
+	| ChannelType.GuildStore,
+	ChannelType.DM | ChannelType.GroupDM
+>;
+
+export interface APITextBasedChannel<T extends ChannelType> extends APIChannelBase<T> {
+	/**
+	 * The id of the last message sent in this channel (may not point to an existing or valid message)
+	 */
+	last_message_id?: Snowflake | null;
+}
+
+export interface APIGuildChannel<T extends ChannelType> extends APIChannelBase<T> {
 	/**
 	 * The id of the guild (may be missing for some channel objects received over gateway guild dispatches)
 	 */
 	guild_id?: Snowflake;
-	/**
-	 * Sorting position of the channel
-	 */
-	position?: number;
 	/**
 	 * Explicit permission overwrites for members and roles
 	 *
@@ -50,17 +70,48 @@ export interface APIChannel extends APIPartialChannel {
 	 */
 	permission_overwrites?: APIOverwrite[];
 	/**
-	 * The channel topic (0-1024 characters)
+	 * Sorting position of the channel
 	 */
-	topic?: string | null;
+	position?: number;
+	/**
+	 * ID of the parent category for a channel (each parent category can contain up to 50 channels)
+	 */
+	parent_id?: Snowflake | null;
 	/**
 	 * Whether the channel is nsfw
 	 */
 	nsfw?: boolean;
+}
+
+export type GuildTextChannelType = Exclude<TextChannelType, ChannelType.DM | ChannelType.GroupDM>;
+
+export interface APIGuildTextChannel<T extends GuildTextChannelType>
+	extends APITextBasedChannel<T>,
+		APIGuildChannel<T> {
 	/**
-	 * The id of the last message sent in this channel (may not point to an existing or valid message)
+	 * The channel topic (0-1024 characters)
 	 */
-	last_message_id?: Snowflake | null;
+	topic?: string | null;
+	/**
+	 * When the last pinned message was pinned.
+	 * This may be `null` in events such as `GUILD_CREATE` when a message is not pinned
+	 */
+	last_pin_timestamp?: string | null;
+}
+
+export interface APITextChannel extends APIGuildTextChannel<ChannelType.GuildText> {
+	/**
+	 * Amount of seconds a user has to wait before sending another message (0-21600);
+	 * bots, as well as users with the permission `MANAGE_MESSAGES` or `MANAGE_CHANNELS`, are unaffected
+	 */
+	rate_limit_per_user?: number;
+}
+
+export type APINewsChannel = APIGuildTextChannel<ChannelType.GuildNews>;
+export type APIGuildCategoryChannel = APIGuildChannel<ChannelType.GuildCategory>;
+export type APIGuildStoreChannel = APIGuildChannel<ChannelType.GuildStore>;
+
+export interface APIVoiceChannel extends APIGuildChannel<ChannelType.GuildStageVoice | ChannelType.GuildVoice> {
 	/**
 	 * The bitrate (in bits) of the voice channel
 	 */
@@ -69,38 +120,6 @@ export interface APIChannel extends APIPartialChannel {
 	 * The user limit of the voice channel
 	 */
 	user_limit?: number;
-	/**
-	 * Amount of seconds a user has to wait before sending another message (0-21600);
-	 * bots, as well as users with the permission `MANAGE_MESSAGES` or `MANAGE_CHANNELS`, are unaffected
-	 */
-	rate_limit_per_user?: number;
-	/**
-	 * The recipients of the DM
-	 *
-	 * See https://discord.com/developers/docs/resources/user#user-object
-	 */
-	recipients?: APIUser[];
-	/**
-	 * Icon hash
-	 */
-	icon?: string | null;
-	/**
-	 * ID of the DM creator
-	 */
-	owner_id?: Snowflake;
-	/**
-	 * Application id of the group DM creator if it is bot-created
-	 */
-	application_id?: Snowflake;
-	/**
-	 * ID of the parent category for a channel (each parent category can contain up to 50 channels)
-	 */
-	parent_id?: Snowflake | null;
-	/**
-	 * When the last pinned message was pinned.
-	 * This may be `null` in events such as `GUILD_CREATE` when a message is not pinned
-	 */
-	last_pin_timestamp?: string | null;
 	/**
 	 * Voice region id for the voice or stage channel, automatic when set to `null`
 	 *
@@ -115,6 +134,49 @@ export interface APIChannel extends APIPartialChannel {
 	video_quality_mode?: VideoQualityMode;
 }
 
+interface APIDMChannelBase<T extends ChannelType> extends APITextBasedChannel<T> {
+	/**
+	 * The recipients of the DM
+	 *
+	 * See https://discord.com/developers/docs/resources/user#user-object
+	 */
+	recipients?: APIUser[];
+}
+
+export type APIDMChannel = APIDMChannelBase<ChannelType.DM>;
+
+export interface APIGroupDMChannel extends APIDMChannelBase<ChannelType.GroupDM> {
+	/**
+	 * Application id of the group DM creator if it is bot-created
+	 */
+	application_id?: Snowflake;
+	/**
+	 * Icon hash
+	 */
+	icon?: string | null;
+	/**
+	 * ID of the DM creator
+	 */
+	owner_id?: Snowflake;
+	/**
+	 * The id of the last message sent in this channel (may not point to an existing or valid message)
+	 */
+	last_message_id?: Snowflake | null;
+}
+
+/**
+ * https://discord.com/developers/docs/resources/channel#channel-object-channel-structure
+ */
+export type APIChannel =
+	| APIGroupDMChannel
+	| APIDMChannel
+	| APITextChannel
+	| APINewsChannel
+	| APIGuildStoreChannel
+	| APIVoiceChannel
+	| APIGuildCategoryChannel
+	| APINewsChannel;
+
 /**
  * https://discord.com/developers/docs/resources/channel#channel-object-channel-types
  */

payloads/v9/channel.ts

@@ -32,17 +32,44 @@ export interface APIPartialChannel {
 }
 
 /**
- * https://discord.com/developers/docs/resources/channel#channel-object-channel-structure
+ * This interface is used to allow easy extension for other channel types. While
+ * also allowing `APIPartialChannel` to be used without breaking.
  */
-export interface APIChannel extends APIPartialChannel {
+export interface APIChannelBase<T extends ChannelType> extends APIPartialChannel {
+	type: T;
+}
+
+// TODO: update when text in voice is released
+export type TextChannelType =
+	| ChannelType.DM
+	| ChannelType.GroupDM
+	| ChannelType.GuildNews
+	| ChannelType.GuildPublicThread
+	| ChannelType.GuildPrivateThread
+	| ChannelType.GuildNewsThread
+	| ChannelType.GuildText;
+
+export type GuildChannelType = Exclude<
+	| TextChannelType
+	| ChannelType.GuildVoice
+	| ChannelType.GuildStageVoice
+	| ChannelType.GuildNews
+	| ChannelType.GuildStore,
+	ChannelType.DM | ChannelType.GroupDM
+>;
+
+export interface APITextBasedChannel<T extends ChannelType> extends APIChannelBase<T> {
+	/**
+	 * The id of the last message sent in this channel (may not point to an existing or valid message)
+	 */
+	last_message_id?: Snowflake | null;
+}
+
+export interface APIGuildChannel<T extends ChannelType> extends APIChannelBase<T> {
 	/**
 	 * The id of the guild (may be missing for some channel objects received over gateway guild dispatches)
 	 */
 	guild_id?: Snowflake;
-	/**
-	 * Sorting position of the channel
-	 */
-	position?: number;
 	/**
 	 * Explicit permission overwrites for members and roles
 	 *
@@ -50,25 +77,44 @@ export interface APIChannel extends APIPartialChannel {
 	 */
 	permission_overwrites?: APIOverwrite[];
 	/**
-	 * The channel topic (0-1024 characters)
+	 * Sorting position of the channel
 	 */
-	topic?: string | null;
+	position?: number;
+	/**
+	 * ID of the parent category for a channel (each parent category can contain up to 50 channels)
+	 *
+	 * OR
+	 *
+	 * ID of the parent channel for a thread
+	 */
+	parent_id?: Snowflake | null;
 	/**
 	 * Whether the channel is nsfw
 	 */
 	nsfw?: boolean;
+}
+
+export type GuildTextChannelType = Exclude<TextChannelType, ChannelType.DM | ChannelType.GroupDM>;
+
+export interface APIGuildTextChannel<T extends GuildTextChannelType>
+	extends APITextBasedChannel<T>,
+		APIGuildChannel<T> {
 	/**
-	 * The id of the last message sent in this channel (may not point to an existing or valid message)
+	 * Default duration for newly created threads, in minutes, to automatically archive the thread after recent activity
 	 */
-	last_message_id?: Snowflake | null;
+	default_auto_archive_duration?: ThreadAutoArchiveDuration;
 	/**
-	 * The bitrate (in bits) of the voice channel
+	 * The channel topic (0-1024 characters)
 	 */
-	bitrate?: number;
+	topic?: string | null;
 	/**
-	 * The user limit of the voice channel
+	 * When the last pinned message was pinned.
+	 * This may be `null` in events such as `GUILD_CREATE` when a message is not pinned
 	 */
-	user_limit?: number;
+	last_pin_timestamp?: string | null;
+}
+
+export interface APITextChannel extends APIGuildTextChannel<ChannelType.GuildText> {
 	/**
 	 * Amount of seconds a user has to wait before sending another message (0-21600);
 	 * bots, as well as users with the permission `MANAGE_MESSAGES` or `MANAGE_CHANNELS`, are unaffected
@@ -79,37 +125,21 @@ export interface APIChannel extends APIPartialChannel {
 	 * The absence of this field in API calls and Gateway events should indicate that slowmode has been reset to the default value.
 	 */
 	rate_limit_per_user?: number;
+}
+
+export type APINewsChannel = APIGuildTextChannel<ChannelType.GuildNews>;
+export type APIGuildCategoryChannel = APIGuildChannel<ChannelType.GuildCategory>;
+export type APIGuildStoreChannel = APIGuildChannel<ChannelType.GuildStore>;
+
+export interface APIVoiceChannel extends APIGuildChannel<ChannelType.GuildStageVoice | ChannelType.GuildVoice> {
 	/**
-	 * The recipients of the DM
-	 *
-	 * See https://discord.com/developers/docs/resources/user#user-object
+	 * The bitrate (in bits) of the voice channel
 	 */
-	recipients?: APIUser[];
+	bitrate?: number;
 	/**
-	 * Icon hash
+	 * The user limit of the voice channel
 	 */
-	icon?: string | null;
-	/**
-	 * ID of the DM creator or thread creator
-	 */
-	owner_id?: Snowflake;
-	/**
-	 * Application id of the group DM creator if it is bot-created
-	 */
-	application_id?: Snowflake;
-	/**
-	 * ID of the parent category for a channel (each parent category can contain up to 50 channels)
-	 *
-	 * OR
-	 *
-	 * ID of the parent channel for a thread
-	 */
-	parent_id?: Snowflake | null;
-	/**
-	 * When the last pinned message was pinned.
-	 * This may be `null` in events such as `GUILD_CREATE` when a message is not pinned
-	 */
-	last_pin_timestamp?: string | null;
+	user_limit?: number;
 	/**
 	 * Voice region id for the voice or stage channel, automatic when set to `null`
 	 *
@@ -122,6 +152,50 @@ export interface APIChannel extends APIPartialChannel {
 	 * See https://discord.com/developers/docs/resources/channel#channel-object-video-quality-modes
 	 */
 	video_quality_mode?: VideoQualityMode;
+}
+
+interface APIDMChannelBase<T extends ChannelType> extends APITextBasedChannel<T> {
+	/**
+	 * The recipients of the DM
+	 *
+	 * See https://discord.com/developers/docs/resources/user#user-object
+	 */
+	recipients?: APIUser[];
+}
+
+export type APIDMChannel = APIDMChannelBase<ChannelType.DM>;
+
+export interface APIGroupDMChannel extends APIDMChannelBase<ChannelType.GroupDM> {
+	/**
+	 * Application id of the group DM creator if it is bot-created
+	 */
+	application_id?: Snowflake;
+	/**
+	 * Icon hash
+	 */
+	icon?: string | null;
+	/**
+	 * ID of the DM creator
+	 */
+	owner_id?: Snowflake;
+	/**
+	 * The id of the last message sent in this channel (may not point to an existing or valid message)
+	 */
+	last_message_id?: Snowflake | null;
+}
+
+export interface APIThreadChannel
+	extends APIGuildChannel<
+		ChannelType.GuildPublicThread | ChannelType.GuildPrivateThread | ChannelType.GuildNewsThread
+	> {
+	/**
+	 * The client users member for the thread, only included in select endpoints
+	 */
+	member?: APIThreadMember;
+	/**
+	 * The metadata for a thread channel not shared by other channels
+	 */
+	thread_metadata?: APIThreadMetadata;
 	/**
 	 * The approximate message count of the thread, does not count above 50 even if there are more messages
 	 */
@@ -131,19 +205,39 @@ export interface APIChannel extends APIPartialChannel {
 	 */
 	member_count?: number;
 	/**
-	 * The metadata for a thread channel not shared by other channels
+	 * Amount of seconds a user has to wait before sending another message (0-21600);
+	 * bots, as well as users with the permission `MANAGE_MESSAGES` or `MANAGE_CHANNELS`, are unaffected
+	 *
+	 * `rate_limit_per_user` also applies to thread creation. Users can send one message and create one thread during each `rate_limit_per_user` interval.
+	 *
+	 * For thread channels, `rate_limit_per_user` is only returned if the field is set to a non-zero and non-null value.
+	 * The absence of this field in API calls and Gateway events should indicate that slowmode has been reset to the default value.
 	 */
-	thread_metadata?: APIThreadMetadata;
+	rate_limit_per_user?: number;
 	/**
-	 * The client users member for the thread, only included in select endpoints
+	 * ID of the thread creator
 	 */
-	member?: APIThreadMember;
+	owner_id?: Snowflake;
 	/**
-	 * Default duration for newly created threads, in minutes, to automatically archive the thread after recent activity
+	 * The id of the last message sent in this thread (may not point to an existing or valid message)
 	 */
-	default_auto_archive_duration?: ThreadAutoArchiveDuration;
+	last_message_id?: Snowflake | null;
 }
 
+/**
+ * https://discord.com/developers/docs/resources/channel#channel-object-channel-structure
+ */
+export type APIChannel =
+	| APIGroupDMChannel
+	| APIDMChannel
+	| APITextChannel
+	| APINewsChannel
+	| APIGuildStoreChannel
+	| APIVoiceChannel
+	| APIGuildCategoryChannel
+	| APIThreadChannel
+	| APINewsChannel;
+
 /**
  * https://discord.com/developers/docs/resources/channel#channel-object-channel-types
  */

rest/v8/guild.ts

@@ -2,7 +2,9 @@ import type { Permissions, Snowflake } from '../../globals';
 import type {
 	APIBan,
 	APIChannel,
+	APIDMChannel,
 	APIExtendedInvite,
+	APIGroupDMChannel,
 	APIGuild,
 	APIGuildIntegration,
 	APIGuildMember,
@@ -25,6 +27,7 @@ import type {
 	Nullable,
 	StrictPartial,
 	StrictRequired,
+	UnionToIntersection,
 } from '../../utils/internals';
 import type { RESTPutAPIChannelPermissionJSONBody } from './channel';
 
@@ -32,8 +35,12 @@ export interface APIGuildCreateOverwrite extends RESTPutAPIChannelPermissionJSON
 	id: number | string;
 }
 
+export type APIGuildChannelResolvable = Exclude<APIChannel, APIDMChannel | APIGroupDMChannel>;
 export type APIGuildCreatePartialChannel = StrictPartial<
-	Pick<APIChannel, 'type' | 'topic' | 'nsfw' | 'bitrate' | 'user_limit' | 'rate_limit_per_user'>
+	Pick<
+		UnionToIntersection<APIGuildChannelResolvable>,
+		'type' | 'topic' | 'nsfw' | 'bitrate' | 'user_limit' | 'rate_limit_per_user'
+	>
 > &
 	AddUndefinedToPossiblyUndefinedPropertiesOfInterface<{
 		name: string;

rest/v9/guild.ts

@@ -20,12 +20,15 @@ import type {
 	GuildSystemChannelFlags,
 	GuildVerificationLevel,
 	GuildWidgetStyle,
+	APIDMChannel,
+	APIGroupDMChannel,
 } from '../../payloads/v9/index';
 import type {
 	AddUndefinedToPossiblyUndefinedPropertiesOfInterface,
 	Nullable,
 	StrictPartial,
 	StrictRequired,
+	UnionToIntersection,
 } from '../../utils/internals';
 import type { RESTPutAPIChannelPermissionJSONBody } from './channel';
 
@@ -33,8 +36,12 @@ export interface APIGuildCreateOverwrite extends RESTPutAPIChannelPermissionJSON
 	id: number | string;
 }
 
+export type APIGuildChannelResolvable = Exclude<APIChannel, APIDMChannel | APIGroupDMChannel>;
 export type APIGuildCreatePartialChannel = StrictPartial<
-	Pick<APIChannel, 'type' | 'topic' | 'nsfw' | 'bitrate' | 'user_limit' | 'rate_limit_per_user'>
+	Pick<
+		UnionToIntersection<APIGuildChannelResolvable>,
+		'type' | 'topic' | 'nsfw' | 'bitrate' | 'user_limit' | 'rate_limit_per_user'
+	>
 > &
 	AddUndefinedToPossiblyUndefinedPropertiesOfInterface<{
 		name: string;

utils/internals.ts

@@ -13,3 +13,5 @@ export type AddUndefinedToPossiblyUndefinedPropertiesOfInterface<Base> = {
 export type StrictPartial<Base> = AddUndefinedToPossiblyUndefinedPropertiesOfInterface<Partial<Base>>;
 
 export type StrictRequired<Base> = Required<{ [K in keyof Base]: Exclude<Base[K], undefined> }>;
+
+export type UnionToIntersection<T> = (T extends any ? (x: T) => any : never) extends (x: infer R) => any ? R : never;