@buape/carbon 0.1.0

package/src/classes/Client.ts

@@ -0,0 +1,249 @@
+import { RequestClient, type RequestClientOptions } from "@buape/carbon-request"
+import {
+	type APIInteraction,
+	InteractionResponseType,
+	InteractionType,
+	Routes
+} from "discord-api-types/v10"
+import { PlatformAlgorithm, isValidRequest } from "discord-verify"
+import { AutoRouter, type IRequestStrict, StatusError, json } from "itty-router"
+import type { BaseCommand } from "../abstracts/BaseCommand.js"
+import { CommandHandler } from "../internals/CommandHandler.js"
+import { ComponentHandler } from "../internals/ComponentHandler.js"
+
+/**
+ * The mode that the client is running in.
+ * Different platforms have different requirements for how processes are handled.
+ */
+export enum ClientMode {
+	NodeJS = "node",
+	CloudflareWorkers = "cloudflare",
+	Bun = "bun",
+	Vercel = "vercel",
+	Web = "web"
+}
+
+/**
+ * The options used for initializing the client
+ */
+export type ClientOptions = {
+	/**
+	 * If you want to have the root route for the interaction handler redirect to a different URL, you can set this.
+	 */
+	redirectUrl?: string
+	/**
+	 * The client ID of the bot
+	 */
+	clientId: string
+	/**
+	 * The public key of the bot, used for interaction verification
+	 */
+	publicKey: string
+	/**
+	 * The token of the bot
+	 */
+	token: string
+	/**
+	 * The mode of the client, generally where you are hosting the bot. If you have a different mode for your local development, make sure to set it to the local one.
+	 * @example
+	 * ```ts
+	 * import { Client, ClientMode } from "@buape/carbon"
+	 *
+	 * const client = new Client({
+	 * 	clientId: "12345678901234567890",
+	 * 	publicKey: "c1a2f941ae8ce6d776f7704d0bb3d46b863e21fda491cdb2bdba6b8bc5fe7269",
+	 * 	token: "MTA4NjEwNTYxMDUxMDE1NTg1Nw.GNt-U8.OSHy-g-5FlfESnu3Z9MEEMJLHiRthXajiXNwiE",
+	 * 	mode: process.env.NODE_ENV === "development" ? ClientMode.NodeJS : ClientMode.CloudflareWorkers
+	 * })
+	 * ```
+	 */
+	mode: ClientMode
+	/**
+	 * The options used to initialize the request client, if you want to customize it.
+	 */
+	requestOptions?: RequestClientOptions
+	/**
+	 * The port to run the server on, if you are using {@link ClientMode.Bun} mode.
+	 */
+	port?: number
+	/**
+	 * Whether the commands should be deployed to Discord automatically.
+	 */
+	autoDeploy?: boolean
+}
+
+/**
+ * The main client used to interact with Discord
+ */
+export class Client {
+	/**
+	 * The options used to initialize the client
+	 */
+	options: ClientOptions
+	/**
+	 * The commands that the client has registered
+	 */
+	commands: BaseCommand[]
+	/**
+	 * The router used to handle requests
+	 */
+	router: ReturnType<typeof AutoRouter<IRequestStrict>>
+	/**
+	 * The rest client used to interact with the Discord API
+	 */
+	rest: RequestClient
+	/**
+	 * The handler for the component interactions sent from Discord
+	 */
+	componentHandler: ComponentHandler
+	commandHandler: CommandHandler
+
+	/**
+	 * Creates a new client
+	 * @param options The options used to initialize the client
+	 * @param commands The commands that the client has registered
+	 */
+	constructor(options: ClientOptions, commands: BaseCommand[]) {
+		if (!options.clientId) throw new Error("Missing client ID")
+		if (!options.publicKey) throw new Error("Missing public key")
+		if (!options.token) throw new Error("Missing token")
+		this.options = options
+		this.commands = commands
+		const routerData =
+			this.options.mode === ClientMode.Bun && this.options.port
+				? { port: this.options.port }
+				: {}
+		// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+		this.router = AutoRouter<IRequestStrict, any[], Response>(routerData)
+		this.rest = new RequestClient(options.token, options.requestOptions)
+		this.componentHandler = new ComponentHandler(this)
+		this.commandHandler = new CommandHandler(this)
+		this.setupRoutes()
+		if (this.options.autoDeploy) this.deployCommands()
+	}
+
+	/**
+	 * Deploy the commands registered to Discord.
+	 * This is automatically called when running in NodeJS mode.
+	 */
+	async deployCommands() {
+		try {
+			const commands = this.commands.map((command) => {
+				return command.serialize()
+			})
+			await this.rest.put(Routes.applicationCommands(this.options.clientId), {
+				body: commands
+			})
+			console.log(`Deployed ${commands.length} commands to Discord`)
+		} catch (err) {
+			console.error("Failed to deploy commands")
+			console.error(err)
+		}
+	}
+
+	/**
+	 * Setup the routes for the client
+	 */
+	private setupRoutes() {
+		this.router.get("/", () => {
+			if (this.options.redirectUrl)
+				return Response.redirect(this.options.redirectUrl, 302)
+			throw new StatusError(404)
+		})
+		this.router.post("/interaction", async (req, ctx?: ExecutionContext) => {
+			const isValid = await this.validateInteraction(req)
+			if (!isValid) {
+				return new Response("Invalid request signature", { status: 401 })
+			}
+
+			const rawInteraction = (await req.json()) as unknown as APIInteraction
+			if (rawInteraction.type === InteractionType.Ping) {
+				return json({
+					type: InteractionResponseType.Pong
+				})
+			}
+
+			if (rawInteraction.type === InteractionType.ApplicationCommand) {
+				if (ctx?.waitUntil) {
+					ctx.waitUntil(
+						(async () => {
+							await this.commandHandler.handleCommandInteraction(rawInteraction)
+						})()
+					)
+				} else {
+					await this.commandHandler.handleCommandInteraction(rawInteraction)
+				}
+			}
+			if (
+				rawInteraction.type === InteractionType.ApplicationCommandAutocomplete
+			) {
+				if (ctx?.waitUntil) {
+					ctx.waitUntil(
+						(async () => {
+							await this.commandHandler.handleAutocompleteInteraction(
+								rawInteraction
+							)
+						})()
+					)
+				} else {
+					await this.commandHandler.handleAutocompleteInteraction(
+						rawInteraction
+					)
+				}
+			}
+			if (rawInteraction.type === InteractionType.ApplicationCommand) {
+				if (ctx?.waitUntil) {
+					ctx.waitUntil(
+						(async () => {
+							await this.commandHandler.handleCommandInteraction(rawInteraction)
+						})()
+					)
+				} else {
+					await this.commandHandler.handleCommandInteraction(rawInteraction)
+				}
+			}
+			if (rawInteraction.type === InteractionType.MessageComponent) {
+				if (ctx?.waitUntil) {
+					ctx.waitUntil(
+						(async () => {
+							await this.componentHandler.handleInteraction(rawInteraction)
+						})()
+					)
+				} else {
+					await this.componentHandler.handleInteraction(rawInteraction)
+				}
+			}
+			return new Response(null, { status: 202 })
+		})
+	}
+
+	/**
+	 * Validate the interaction request
+	 * @param req The request to validate
+	 */
+	private async validateInteraction(req: IRequestStrict) {
+		if (req.method !== "POST") {
+			throw new StatusError(405)
+		}
+		const isValid = await isValidRequest(
+			req,
+			this.options.publicKey,
+			this.options.mode === ClientMode.CloudflareWorkers
+				? PlatformAlgorithm.Cloudflare
+				: this.options.mode === ClientMode.Vercel
+					? PlatformAlgorithm.VercelProd
+					: this.options.mode === ClientMode.Web
+						? PlatformAlgorithm.Web
+						: PlatformAlgorithm.NewNode
+		)
+		return isValid
+	}
+}
+
+/**
+ * @hidden
+ */
+export interface ExecutionContext {
+	// biome-ignore lint/suspicious/noExplicitAny: true any
+	waitUntil(promise: Promise<any>): void
+}

package/src/classes/Command.ts

@@ -0,0 +1,51 @@
+import {
+	type APIApplicationCommandBasicOption,
+	ApplicationCommandType
+} from "discord-api-types/v10"
+import { BaseCommand } from "../abstracts/BaseCommand.js"
+import type { CommandInteraction } from "../internals/CommandInteraction.js"
+import type { AutocompleteInteraction } from "../internals/AutocompleteInteraction.js"
+
+export type CommandOptions = APIApplicationCommandBasicOption[]
+
+/**
+ * Represents a standard command that the user creates
+ */
+export abstract class Command extends BaseCommand {
+	/**
+	 * The options that the user passes along with the command in Discord
+	 */
+	options?: CommandOptions
+
+	/**
+	 * The type of command, either ChatInput, User, or Message. User and Message are context menu commands.
+	 * @default ChatInput
+	 */
+	type: ApplicationCommandType = ApplicationCommandType.ChatInput
+
+	/**
+	 * The function that is called when the command is ran
+	 * @param interaction The interaction that triggered the command
+	 */
+	abstract run(interaction: CommandInteraction): Promise<void>
+
+	/**
+	 * The function that is called when the command's autocomplete is triggered.
+	 * @param interaction The interaction that triggered the autocomplete
+	 * @remarks You are expected to `override` this function to provide your own autocomplete functionality.
+	 */
+	public async autocomplete(
+		interaction: AutocompleteInteraction
+	): Promise<void> {
+		throw new Error(
+			`The ${interaction.rawData.data.name} command does not support autocomplete`
+		)
+	}
+
+	/**
+	 * @internal
+	 */
+	serializeOptions() {
+		return this.options
+	}
+}

package/src/classes/CommandWithSubcommandGroups.ts

@@ -0,0 +1,47 @@
+import {
+	type APIApplicationCommandBasicOption,
+	type APIApplicationCommandSubcommandGroupOption,
+	type APIApplicationCommandSubcommandOption,
+	ApplicationCommandOptionType
+} from "discord-api-types/v10"
+import type { Command } from "./Command.js"
+import { CommandWithSubcommands } from "./CommandWithSubcommands.js"
+
+/**
+ * Represents a subcommand group command that the user creates.
+ * You make this instead of a {@link Command} class when you want to have subcommand groups in your options.
+ */
+export abstract class CommandWithSubcommandGroups extends CommandWithSubcommands {
+	/**
+	 * The subcommands that the user can use
+	 */
+	subcommands: Command[] = []
+
+	/**
+	 * The subcommands that the user can use
+	 */
+	abstract subcommandGroups: CommandWithSubcommands[]
+
+	/**
+	 * @internal
+	 */
+	serializeOptions() {
+		const subcommands = this.subcommands.map((subcommand) => ({
+			name: subcommand.name,
+			description: subcommand.description,
+			type: ApplicationCommandOptionType.Subcommand,
+			options:
+				subcommand.serializeOptions() as APIApplicationCommandBasicOption[]
+		})) as APIApplicationCommandSubcommandOption[]
+
+		const subcommandGroups = this.subcommandGroups.map((subcommandGroup) => ({
+			name: subcommandGroup.name,
+			description: subcommandGroup.description,
+			type: ApplicationCommandOptionType.SubcommandGroup,
+			options:
+				subcommandGroup.serializeOptions() as APIApplicationCommandSubcommandOption[]
+		})) as APIApplicationCommandSubcommandGroupOption[]
+
+		return [...subcommands, ...subcommandGroups]
+	}
+}

package/src/classes/CommandWithSubcommands.ts

@@ -0,0 +1,35 @@
+import {
+	type APIApplicationCommandBasicOption,
+	type APIApplicationCommandSubcommandOption,
+	ApplicationCommandOptionType,
+	ApplicationCommandType,
+	type RESTPostAPIApplicationCommandsJSONBody
+} from "discord-api-types/v10"
+import { BaseCommand } from "../abstracts/BaseCommand.js"
+import type { Command } from "./Command.js"
+
+/**
+ * Represents a subcommand command that the user creates.
+ * You make this instead of a {@link Command} class when you want to have subcommands in your options.
+ */
+export abstract class CommandWithSubcommands extends BaseCommand {
+	type = ApplicationCommandType.ChatInput
+
+	/**
+	 * The subcommands that the user can use
+	 */
+	abstract subcommands: Command[]
+
+	/**
+	 * @internal
+	 */
+	serializeOptions(): RESTPostAPIApplicationCommandsJSONBody["options"] {
+		return this.subcommands.map((subcommand) => ({
+			name: subcommand.name,
+			description: subcommand.description,
+			type: ApplicationCommandOptionType.Subcommand,
+			options:
+				subcommand.serializeOptions() as APIApplicationCommandBasicOption[]
+		})) as APIApplicationCommandSubcommandOption[]
+	}
+}

package/src/classes/MentionableSelectMenu.ts

@@ -0,0 +1,19 @@
+import {
+	type APIMentionableSelectComponent,
+	ComponentType
+} from "discord-api-types/v10"
+import { AnySelectMenu } from "../abstracts/AnySelectMenu.js"
+import type { MentionableSelectMenuInteraction } from "../internals/MentionableSelectMenuInteraction.js"
+
+export abstract class MentionableSelectMenu extends AnySelectMenu {
+	type: ComponentType.MentionableSelect = ComponentType.MentionableSelect
+	defaultValues?: APIMentionableSelectComponent["default_values"]
+	abstract run(interaction: MentionableSelectMenuInteraction): Promise<void>
+
+	serializeOptions() {
+		return {
+			type: this.type,
+			default_values: this.defaultValues
+		}
+	}
+}

package/src/classes/RoleSelectMenu.ts

@@ -0,0 +1,19 @@
+import {
+	type APIRoleSelectComponent,
+	ComponentType
+} from "discord-api-types/v10"
+import { AnySelectMenu } from "../abstracts/AnySelectMenu.js"
+import type { RoleSelectMenuInteraction } from "../internals/RoleSelectMenuInteraction.js"
+
+export abstract class RoleSelectMenu extends AnySelectMenu {
+	type: ComponentType.RoleSelect = ComponentType.RoleSelect
+	defaultValues?: APIRoleSelectComponent["default_values"]
+	abstract run(interaction: RoleSelectMenuInteraction): Promise<void>
+
+	serializeOptions() {
+		return {
+			type: this.type,
+			default_values: this.defaultValues
+		}
+	}
+}

package/src/classes/Row.ts

@@ -0,0 +1,44 @@
+import type { BaseComponent } from "../abstracts/BaseComponent.js"
+
+export class Row {
+	/**
+	 * The components in the action row
+	 */
+	components: BaseComponent[]
+
+	constructor(components: BaseComponent[]) {
+		this.components = components
+	}
+
+	/**
+	 * Add a component to the action row
+	 * @param component The component to add
+	 */
+	addComponent(component: BaseComponent) {
+		this.components.push(component)
+	}
+
+	/**
+	 * Remove a component from the action row
+	 * @param component The component to remove
+	 */
+	removeComponent(component: BaseComponent) {
+		const index = this.components.indexOf(component)
+		if (index === -1) return
+		this.components.splice(index, 1)
+	}
+
+	/**
+	 * Remove all components from the action row
+	 */
+	removeAllComponents() {
+		this.components = []
+	}
+
+	serialize() {
+		return {
+			type: 1,
+			components: this.components.map((component) => component.serialize())
+		}
+	}
+}

package/src/classes/StringSelectMenu.ts

@@ -0,0 +1,19 @@
+import {
+	type APIStringSelectComponent,
+	ComponentType
+} from "discord-api-types/v10"
+import { AnySelectMenu } from "../abstracts/AnySelectMenu.js"
+import type { StringSelectMenuInteraction } from "../internals/StringSelectMenuInteraction.js"
+
+export abstract class StringSelectMenu extends AnySelectMenu {
+	type: ComponentType.StringSelect = ComponentType.StringSelect
+	abstract options: APIStringSelectComponent["options"]
+	abstract run(interaction: StringSelectMenuInteraction): Promise<void>
+
+	serializeOptions() {
+		return {
+			type: this.type,
+			options: this.options
+		}
+	}
+}

package/src/classes/UserSelectMenu.ts

@@ -0,0 +1,19 @@
+import {
+	type APIUserSelectComponent,
+	ComponentType
+} from "discord-api-types/v10"
+import { AnySelectMenu } from "../abstracts/AnySelectMenu.js"
+import type { UserSelectMenuInteraction } from "../internals/UserSelectMenuInteraction.js"
+
+export abstract class UserSelectMenu extends AnySelectMenu {
+	type: ComponentType.UserSelect = ComponentType.UserSelect
+	defaultValues?: APIUserSelectComponent["default_values"]
+	abstract run(interaction: UserSelectMenuInteraction): Promise<void>
+
+	serializeOptions() {
+		return {
+			type: this.type,
+			default_values: this.defaultValues
+		}
+	}
+}

package/src/factories/channelFactory.ts

@@ -0,0 +1,43 @@
+import { type APIChannel, ChannelType } from "discord-api-types/v10"
+import type { Client } from "../classes/Client.js"
+import { DmChannel } from "../structures/DmChannel.js"
+import { GroupDmChannel } from "../structures/GroupDmChannel.js"
+import { GuildAnnouncementChannel } from "../structures/GuildAnnouncementChannel.js"
+import { GuildCategoryChannel } from "../structures/GuildCategoryChannel.js"
+import { GuildForumChannel } from "../structures/GuildForumChannel.js"
+import { GuildMediaChannel } from "../structures/GuildMediaChannel.js"
+import {
+	GuildStageChannel,
+	GuildVoiceChannel
+} from "../structures/GuildStageOrVoiceChannel.js"
+import { GuildTextChannel } from "../structures/GuildTextChannel.js"
+import { GuildThreadChannel } from "../structures/GuildThreadChannel.js"
+
+export const channelFactory = (client: Client, channelData: APIChannel) => {
+	switch (channelData.type) {
+		case ChannelType.DM:
+			return new DmChannel(client, channelData)
+		case ChannelType.GroupDM:
+			return new GroupDmChannel(client, channelData)
+		case ChannelType.GuildText:
+			return new GuildTextChannel(client, channelData)
+		case ChannelType.GuildVoice:
+			return new GuildVoiceChannel(client, channelData)
+		case ChannelType.GuildCategory:
+			return new GuildCategoryChannel(client, channelData)
+		case ChannelType.GuildAnnouncement:
+			return new GuildAnnouncementChannel(client, channelData)
+		case ChannelType.AnnouncementThread:
+		case ChannelType.PublicThread:
+		case ChannelType.PrivateThread:
+			return new GuildThreadChannel(client, channelData)
+		case ChannelType.GuildStageVoice:
+			return new GuildStageChannel(client, channelData)
+		case ChannelType.GuildForum:
+			return new GuildForumChannel(client, channelData)
+		case ChannelType.GuildMedia:
+			return new GuildMediaChannel(client, channelData)
+		default:
+			return null
+	}
+}

package/src/index.ts

@@ -0,0 +1,59 @@
+// ----- Abstracts -----
+export * from "./abstracts/AnySelectMenu.js"
+export * from "./abstracts/AnySelectMenuInteraction.js"
+export * from "./abstracts/Base.js"
+export * from "./abstracts/BaseChannel.js"
+export * from "./abstracts/BaseCommand.js"
+export * from "./abstracts/BaseComponent.js"
+export * from "./abstracts/BaseComponentInteraction.js"
+export * from "./abstracts/BaseGuildChannel.js"
+export * from "./abstracts/BaseGuildTextChannel.js"
+export * from "./abstracts/BaseInteraction.js"
+export * from "./abstracts/GuildThreadOnlyChannel.js"
+
+// ----- Classes -----
+export * from "./classes/Button.js"
+export * from "./classes/ChannelSelectMenu.js"
+export * from "./classes/Client.js"
+export * from "./classes/Command.js"
+export * from "./classes/CommandWithSubcommandGroups.js"
+export * from "./classes/CommandWithSubcommands.js"
+export * from "./classes/MentionableSelectMenu.js"
+export * from "./classes/RoleSelectMenu.js"
+export * from "./classes/Row.js"
+export * from "./classes/StringSelectMenu.js"
+export * from "./classes/UserSelectMenu.js"
+
+// ----- Factories -----
+export * from "./factories/channelFactory.js"
+
+// ----- Internals -----
+export * from "./internals/AutocompleteInteraction.js"
+export * from "./internals/ButtonInteraction.js"
+export * from "./internals/ChannelSelectMenuInteraction.js"
+export * from "./internals/CommandHandler.js"
+export * from "./internals/CommandInteraction.js"
+export * from "./internals/ComponentHandler.js"
+export * from "./internals/MentionableSelectMenuInteraction.js"
+export * from "./internals/OptionsHandler.js"
+export * from "./internals/RoleSelectMenuInteraction.js"
+export * from "./internals/StringSelectMenuInteraction.js"
+export * from "./internals/UserSelectMenuInteraction.js"
+
+// ----- Structures -----
+export * from "./structures/DmChannel.js"
+export * from "./structures/GroupDmChannel.js"
+export * from "./structures/Guild.js"
+export * from "./structures/GuildAnnouncementChannel.js"
+export * from "./structures/GuildCategoryChannel.js"
+export * from "./structures/GuildForumChannel.js"
+export * from "./structures/GuildMediaChannel.js"
+export * from "./structures/GuildStageOrVoiceChannel.js"
+export * from "./structures/GuildTextChannel.js"
+export * from "./structures/GuildThreadChannel.js"
+export * from "./structures/Message.js"
+export * from "./structures/Role.js"
+export * from "./structures/User.js"
+
+// ----- Types -----
+export * from "discord-api-types/v10"