@ovencord/builders 1.11.1

package/src/interactions/commands/Command.ts

@@ -0,0 +1,87 @@
+import type { JSONEncodable } from '@ovencord/util';
+import type {
+	ApplicationIntegrationType,
+	InteractionContextType,
+	Permissions,
+	RESTPostAPIApplicationCommandsJSONBody,
+} from 'discord-api-types/v10';
+import type { RestOrArray } from '../../util/normalizeArray.js';
+import { normalizeArray } from '../../util/normalizeArray.js';
+
+export interface CommandData extends Partial<
+	Pick<RESTPostAPIApplicationCommandsJSONBody, 'contexts' | 'default_member_permissions' | 'integration_types' | 'nsfw'>
+> {}
+
+/**
+ * The base class for all command builders.
+ */
+export abstract class CommandBuilder<
+	Command extends RESTPostAPIApplicationCommandsJSONBody,
+> implements JSONEncodable<Command> {
+	/**
+	 * The API data associated with this command.
+	 *
+	 * @internal
+	 */
+	declare protected readonly data: CommandData;
+
+	/**
+	 * Sets the contexts of this command.
+	 *
+	 * @param contexts - The contexts
+	 */
+	public setContexts(...contexts: RestOrArray<InteractionContextType>) {
+		this.data.contexts = normalizeArray(contexts);
+		return this;
+	}
+
+	/**
+	 * Sets the integration types of this command.
+	 *
+	 * @param integrationTypes - The integration types
+	 */
+	public setIntegrationTypes(...integrationTypes: RestOrArray<ApplicationIntegrationType>) {
+		this.data.integration_types = normalizeArray(integrationTypes);
+		return this;
+	}
+
+	/**
+	 * Sets the default permissions a member should have in order to run the command.
+	 *
+	 * @remarks
+	 * You can set this to `'0'` to disable the command by default.
+	 * @param permissions - The permissions bit field to set
+	 * @see {@link https://discord.com/developers/docs/interactions/application-commands#permissions}
+	 */
+	public setDefaultMemberPermissions(permissions: Permissions | bigint | number) {
+		this.data.default_member_permissions = typeof permissions === 'string' ? permissions : permissions.toString();
+		return this;
+	}
+
+	/**
+	 * Clears the default permissions a member should have in order to run the command.
+	 */
+	public clearDefaultMemberPermissions() {
+		this.data.default_member_permissions = undefined;
+		return this;
+	}
+
+	/**
+	 * Sets whether this command is NSFW.
+	 *
+	 * @param nsfw - Whether this command is NSFW
+	 */
+	public setNSFW(nsfw = true) {
+		this.data.nsfw = nsfw;
+		return this;
+	}
+
+	/**
+	 * Serializes this builder to API-compatible JSON data.
+	 *
+	 * Note that by disabling validation, there is no guarantee that the resulting object will be valid.
+	 *
+	 * @param validationOverride - Force validation to run/not run regardless of your global preference
+	 */
+	public abstract toJSON(validationOverride?: boolean): Command;
+}

package/src/interactions/commands/SharedName.ts

@@ -0,0 +1,68 @@
+import type { Locale, RESTPostAPIApplicationCommandsJSONBody } from 'discord-api-types/v10';
+
+export interface SharedNameData extends Partial<
+	Pick<RESTPostAPIApplicationCommandsJSONBody, 'name_localizations' | 'name'>
+> {}
+
+/**
+ * This mixin holds name and description symbols for chat input commands.
+ */
+export class SharedName {
+	/**
+	 * @internal
+	 */
+	protected readonly data: SharedNameData = {};
+
+	/**
+	 * Sets the name of this command.
+	 *
+	 * @param name - The name to use
+	 */
+	public setName(name: string): this {
+		this.data.name = name;
+		return this;
+	}
+
+	/**
+	 * Sets a name localization for this command.
+	 *
+	 * @param locale - The locale to set
+	 * @param localizedName - The localized name for the given `locale`
+	 */
+	public setNameLocalization(locale: Locale, localizedName: string) {
+		this.data.name_localizations ??= {};
+		this.data.name_localizations[locale] = localizedName;
+
+		return this;
+	}
+
+	/**
+	 * Clears a name localization for this command.
+	 *
+	 * @param locale - The locale to clear
+	 */
+	public clearNameLocalization(locale: Locale) {
+		this.data.name_localizations ??= {};
+		this.data.name_localizations[locale] = undefined;
+
+		return this;
+	}
+
+	/**
+	 * Sets the name localizations for this command.
+	 *
+	 * @param localizedNames - The object of localized names to set
+	 */
+	public setNameLocalizations(localizedNames: Partial<Record<Locale, string>>) {
+		this.data.name_localizations = structuredClone(localizedNames);
+		return this;
+	}
+
+	/**
+	 * Clears all name localizations for this command.
+	 */
+	public clearNameLocalizations() {
+		this.data.name_localizations = undefined;
+		return this;
+	}
+}

package/src/interactions/commands/SharedNameAndDescription.ts

@@ -0,0 +1,69 @@
+import type { APIApplicationCommand, Locale } from 'discord-api-types/v10';
+import type { SharedNameData } from './SharedName.js';
+import { SharedName } from './SharedName.js';
+
+export interface SharedNameAndDescriptionData
+	extends SharedNameData, Partial<Pick<APIApplicationCommand, 'description_localizations' | 'description'>> {}
+
+/**
+ * This mixin holds name and description symbols for chat input commands.
+ */
+export class SharedNameAndDescription extends SharedName {
+	/**
+	 * @internal
+	 */
+	protected override readonly data: SharedNameAndDescriptionData = {};
+
+	/**
+	 * Sets the description of this command.
+	 *
+	 * @param description - The description to use
+	 */
+	public setDescription(description: string) {
+		this.data.description = description;
+		return this;
+	}
+
+	/**
+	 * Sets a description localization for this command.
+	 *
+	 * @param locale - The locale to set
+	 * @param localizedDescription - The localized description for the given `locale`
+	 */
+	public setDescriptionLocalization(locale: Locale, localizedDescription: string) {
+		this.data.description_localizations ??= {};
+		this.data.description_localizations[locale] = localizedDescription;
+
+		return this;
+	}
+
+	/**
+	 * Clears a description localization for this command.
+	 *
+	 * @param locale - The locale to clear
+	 */
+	public clearDescriptionLocalization(locale: Locale) {
+		this.data.description_localizations ??= {};
+		this.data.description_localizations[locale] = undefined;
+
+		return this;
+	}
+
+	/**
+	 * Sets the description localizations for this command.
+	 *
+	 * @param localizedDescriptions - The object of localized descriptions to set
+	 */
+	public setDescriptionLocalizations(localizedDescriptions: Partial<Record<Locale, string>>) {
+		this.data.description_localizations = structuredClone(localizedDescriptions);
+		return this;
+	}
+
+	/**
+	 * Clears all description localizations for this command.
+	 */
+	public clearDescriptionLocalizations() {
+		this.data.description_localizations = undefined;
+		return this;
+	}
+}

package/src/interactions/commands/chatInput/Assertions.ts

@@ -0,0 +1,180 @@
+import {
+	ApplicationIntegrationType,
+	InteractionContextType,
+	ApplicationCommandOptionType,
+	ApplicationCommandType,
+} from 'discord-api-types/v10';
+import { z } from 'zod';
+import { localeMapPredicate, memberPermissionsPredicate } from '../../../Assertions.js';
+import { ApplicationCommandOptionAllowedChannelTypes } from './mixins/ApplicationCommandOptionChannelTypesMixin.js';
+
+const namePredicate = z
+	.string()
+	.min(1)
+	.max(32)
+	.regex(/^[\p{Ll}\p{Lm}\p{Lo}\p{N}\p{sc=Devanagari}\p{sc=Thai}_-]+$/u);
+
+const descriptionPredicate = z.string().min(1).max(100);
+
+const sharedNameAndDescriptionPredicate = z.object({
+	name: namePredicate,
+	name_localizations: localeMapPredicate.optional(),
+	description: descriptionPredicate,
+	description_localizations: localeMapPredicate.optional(),
+});
+
+const numericMixinNumberOptionPredicate = z.object({
+	max_value: z.number().optional(),
+	min_value: z.number().optional(),
+});
+
+const numericMixinIntegerOptionPredicate = z.object({
+	max_value: z.number().int().optional(),
+	min_value: z.number().int().optional(),
+});
+
+const channelMixinOptionPredicate = z.object({
+	channel_types: z.union(ApplicationCommandOptionAllowedChannelTypes.map(type => z.literal(type)) as any).array().optional(),
+});
+
+const autocompleteMixinOptionPredicate = z.object({
+	autocomplete: z.literal(true),
+	choices: z.union([z.never(), z.never().array(), z.undefined()]).optional(),
+});
+
+const choiceValueStringPredicate = z.string().min(1).max(100);
+const choiceValueNumberPredicate = z.number();
+const choiceBasePredicate = z.object({
+	name: choiceValueStringPredicate,
+	name_localizations: localeMapPredicate.optional(),
+});
+const choiceStringPredicate = z.object({
+	...choiceBasePredicate.shape,
+	value: choiceValueStringPredicate,
+});
+const choiceNumberPredicate = z.object({
+	...choiceBasePredicate.shape,
+	value: choiceValueNumberPredicate,
+});
+
+const choiceBaseMixinPredicate = z.object({
+	autocomplete: z.literal(false).optional(),
+});
+const choiceStringMixinPredicate = z.object({
+	...choiceBaseMixinPredicate.shape,
+	choices: choiceStringPredicate.array().max(25).optional(),
+});
+const choiceNumberMixinPredicate = z.object({
+	...choiceBaseMixinPredicate.shape,
+	choices: choiceNumberPredicate.array().max(25).optional(),
+});
+
+export const baseBasicOptionPredicate = z.object({
+	...sharedNameAndDescriptionPredicate.shape,
+	required: z.boolean().optional(),
+});
+
+export const attachmentOptionPredicate = z.object({
+	...baseBasicOptionPredicate.shape,
+	type: z.literal(ApplicationCommandOptionType.Attachment),
+});
+
+export const booleanOptionPredicate = z.object({
+	...baseBasicOptionPredicate.shape,
+	type: z.literal(ApplicationCommandOptionType.Boolean),
+});
+
+export const mentionableOptionPredicate = z.object({
+	...baseBasicOptionPredicate.shape,
+	type: z.literal(ApplicationCommandOptionType.Mentionable),
+});
+
+export const roleOptionPredicate = z.object({
+	...baseBasicOptionPredicate.shape,
+	type: z.literal(ApplicationCommandOptionType.Role),
+});
+
+export const userOptionPredicate = z.object({
+	...baseBasicOptionPredicate.shape,
+	type: z.literal(ApplicationCommandOptionType.User),
+});
+
+const autocompleteOrStringChoicesMixinOptionPredicate = z.discriminatedUnion('autocomplete', [
+	autocompleteMixinOptionPredicate,
+	choiceStringMixinPredicate,
+]);
+
+const autocompleteOrNumberChoicesMixinOptionPredicate = z.discriminatedUnion('autocomplete', [
+	autocompleteMixinOptionPredicate,
+	choiceNumberMixinPredicate,
+]);
+
+export const channelOptionPredicate = z.object({
+	...baseBasicOptionPredicate.shape,
+	...channelMixinOptionPredicate.shape,
+	type: z.literal(ApplicationCommandOptionType.Channel),
+});
+
+export const integerOptionPredicate = z
+	.object({
+		...baseBasicOptionPredicate.shape,
+		...numericMixinIntegerOptionPredicate.shape,
+		type: z.literal(ApplicationCommandOptionType.Integer),
+	})
+	.and(autocompleteOrNumberChoicesMixinOptionPredicate);
+
+export const numberOptionPredicate = z
+	.object({
+		...baseBasicOptionPredicate.shape,
+		...numericMixinNumberOptionPredicate.shape,
+		type: z.literal(ApplicationCommandOptionType.Number),
+	})
+	.and(autocompleteOrNumberChoicesMixinOptionPredicate);
+
+export const stringOptionPredicate = z
+	.object({
+		...baseBasicOptionPredicate.shape,
+		max_length: z.number().min(1).max(6_000).optional(),
+		min_length: z.number().min(0).max(6_000).optional(),
+		type: z.literal(ApplicationCommandOptionType.String),
+	})
+	.and(autocompleteOrStringChoicesMixinOptionPredicate);
+
+const basicOptionPredicates = [
+	attachmentOptionPredicate,
+	booleanOptionPredicate,
+	channelOptionPredicate,
+	integerOptionPredicate,
+	mentionableOptionPredicate,
+	numberOptionPredicate,
+	roleOptionPredicate,
+	stringOptionPredicate,
+	userOptionPredicate,
+];
+
+export const chatInputCommandSubcommandPredicate = z.object({
+	...sharedNameAndDescriptionPredicate.shape,
+	type: z.literal(ApplicationCommandOptionType.Subcommand),
+	options: z.array(z.union(basicOptionPredicates as any)).max(25).optional(),
+});
+
+export const chatInputCommandSubcommandGroupPredicate = z.object({
+	...sharedNameAndDescriptionPredicate.shape,
+	type: z.literal(ApplicationCommandOptionType.SubcommandGroup),
+	options: z.array(chatInputCommandSubcommandPredicate).min(1).max(25),
+});
+
+export const chatInputCommandPredicate = z.object({
+	...sharedNameAndDescriptionPredicate.shape,
+	contexts: z.array(z.nativeEnum(InteractionContextType)).optional(),
+	default_member_permissions: memberPermissionsPredicate.optional(),
+	integration_types: z.array(z.nativeEnum(ApplicationIntegrationType)).optional(),
+	nsfw: z.boolean().optional(),
+	options: z
+		.union([
+			z.array(z.union(basicOptionPredicates as any)).max(25),
+			z.array(z.union([chatInputCommandSubcommandPredicate, chatInputCommandSubcommandGroupPredicate])).max(25),
+		])
+		.optional(),
+	type: z.literal(ApplicationCommandType.ChatInput).optional(),
+});

package/src/interactions/commands/chatInput/ChatInputCommand.ts

@@ -0,0 +1,40 @@
+import { ApplicationCommandType, type RESTPostAPIChatInputApplicationCommandsJSONBody } from 'discord-api-types/v10';
+import { Mixin } from 'ts-mixer';
+import { validate } from '../../../util/validation.js';
+import { CommandBuilder } from '../Command.js';
+import { SharedNameAndDescription } from '../SharedNameAndDescription.js';
+import { chatInputCommandPredicate } from './Assertions.js';
+import { SharedChatInputCommandOptions } from './mixins/SharedChatInputCommandOptions.js';
+import { SharedChatInputCommandSubcommands } from './mixins/SharedSubcommands.js';
+
+/**
+ * A builder that creates API-compatible JSON data for chat input commands.
+ *
+ * @mixes {@link CommandBuilder}\<{@link discord-api-types/v10#(RESTPostAPIChatInputApplicationCommandsJSONBody:interface)}\>
+ * @mixes {@link SharedChatInputCommandOptions}
+ * @mixes {@link SharedNameAndDescription}
+ * @mixes {@link SharedChatInputCommandSubcommands}
+ */
+export class ChatInputCommandBuilder extends Mixin(
+	CommandBuilder<RESTPostAPIChatInputApplicationCommandsJSONBody>,
+	SharedChatInputCommandOptions,
+	SharedNameAndDescription,
+	SharedChatInputCommandSubcommands,
+) {
+	/**
+	 * {@inheritDoc CommandBuilder.toJSON}
+	 */
+	public toJSON(validationOverride?: boolean): RESTPostAPIChatInputApplicationCommandsJSONBody {
+		const { options, ...rest } = this.data;
+
+		const data: RESTPostAPIChatInputApplicationCommandsJSONBody = {
+			...structuredClone(rest as Omit<RESTPostAPIChatInputApplicationCommandsJSONBody, 'options'>),
+			type: ApplicationCommandType.ChatInput,
+			options: options?.map((option) => option.toJSON(false)),
+		};
+
+		validate(chatInputCommandPredicate, data, validationOverride);
+
+		return data;
+	}
+}

package/src/interactions/commands/chatInput/ChatInputCommandSubcommands.ts

@@ -0,0 +1,117 @@
+import type { JSONEncodable } from '@ovencord/util';
+import type {
+	APIApplicationCommandSubcommandOption,
+	APIApplicationCommandSubcommandGroupOption,
+} from 'discord-api-types/v10';
+import { ApplicationCommandOptionType } from 'discord-api-types/v10';
+import { Mixin } from 'ts-mixer';
+import { normalizeArray, type RestOrArray } from '../../../util/normalizeArray.js';
+import { resolveBuilder } from '../../../util/resolveBuilder.js';
+import { validate } from '../../../util/validation.js';
+import type { SharedNameAndDescriptionData } from '../SharedNameAndDescription.js';
+import { SharedNameAndDescription } from '../SharedNameAndDescription.js';
+import { chatInputCommandSubcommandGroupPredicate, chatInputCommandSubcommandPredicate } from './Assertions.js';
+import { SharedChatInputCommandOptions } from './mixins/SharedChatInputCommandOptions.js';
+
+export interface ChatInputCommandSubcommandGroupData {
+	options?: ChatInputCommandSubcommandBuilder[];
+}
+
+/**
+ * Represents a folder for subcommands.
+ *
+ * @see {@link https://discord.com/developers/docs/interactions/application-commands#subcommands-and-subcommand-groups}
+ */
+export class ChatInputCommandSubcommandGroupBuilder
+	extends SharedNameAndDescription
+	implements JSONEncodable<APIApplicationCommandSubcommandGroupOption>
+{
+	/**
+	 * The API data associated with this subcommand group.
+	 *
+	 * @internal
+	 */
+	declare protected readonly data: ChatInputCommandSubcommandGroupData & SharedNameAndDescriptionData;
+
+	/**
+	 * The options within this subcommand group.
+	 */
+	public get options(): readonly ChatInputCommandSubcommandBuilder[] {
+		return (this.data.options ??= []);
+	}
+
+	/**
+	 * Adds a new subcommand to this group.
+	 *
+	 * @param input - A function that returns a subcommand builder or an already built builder
+	 */
+	public addSubcommands(
+		...input: RestOrArray<
+			| ChatInputCommandSubcommandBuilder
+			| ((subcommandGroup: ChatInputCommandSubcommandBuilder) => ChatInputCommandSubcommandBuilder)
+		>
+	) {
+		const normalized = normalizeArray(input);
+		 
+		const result = normalized.map((builder) => resolveBuilder(builder, ChatInputCommandSubcommandBuilder));
+
+		this.data.options ??= [];
+		this.data.options.push(...result);
+
+		return this;
+	}
+
+	/**
+	 * Serializes this builder to API-compatible JSON data.
+	 *
+	 * Note that by disabling validation, there is no guarantee that the resulting object will be valid.
+	 *
+	 * @param validationOverride - Force validation to run/not run regardless of your global preference
+	 */
+	public toJSON(validationOverride?: boolean): APIApplicationCommandSubcommandGroupOption {
+		const { options, ...rest } = this.data;
+
+		const data = {
+			...(structuredClone(rest) as Omit<APIApplicationCommandSubcommandGroupOption, 'type'>),
+			type: ApplicationCommandOptionType.SubcommandGroup as const,
+			options: options?.map((option) => option.toJSON(validationOverride)) ?? [],
+		};
+
+		validate(chatInputCommandSubcommandGroupPredicate, data, validationOverride);
+
+		return data;
+	}
+}
+
+/**
+ * A builder that creates API-compatible JSON data for chat input command subcommands.
+ *
+ * @mixes {@link SharedNameAndDescription}
+ * @mixes {@link SharedChatInputCommandOptions}
+ * @see {@link https://discord.com/developers/docs/interactions/application-commands#subcommands-and-subcommand-groups}
+ */
+export class ChatInputCommandSubcommandBuilder
+	extends Mixin(SharedNameAndDescription, SharedChatInputCommandOptions)
+	implements JSONEncodable<APIApplicationCommandSubcommandOption>
+{
+	/**
+	 * Serializes this builder to API-compatible JSON data.
+	 *
+	 * Note that by disabling validation, there is no guarantee that the resulting object will be valid.
+	 *
+	 * @param validationOverride - Force validation to run/not run regardless of your global preference
+	 */
+	public toJSON(validationOverride?: boolean): APIApplicationCommandSubcommandOption {
+		const { options, ...rest } = this.data;
+
+		const data = {
+			...(structuredClone(rest) as Omit<APIApplicationCommandSubcommandOption, 'type'>),
+			type: ApplicationCommandOptionType.Subcommand as const,
+			options: options?.map((option) => option.toJSON(validationOverride)) ?? [],
+		};
+
+		validate(chatInputCommandSubcommandPredicate, data, validationOverride);
+
+		return data;
+	}
+}

package/src/interactions/commands/chatInput/mixins/ApplicationCommandNumericOptionMinMaxValueMixin.ts

@@ -0,0 +1,52 @@
+import type { APIApplicationCommandIntegerOption } from 'discord-api-types/v10';
+
+export interface ApplicationCommandNumericOptionMinMaxValueData extends Pick<
+	APIApplicationCommandIntegerOption,
+	'max_value' | 'min_value'
+> {}
+
+/**
+ * This mixin holds minimum and maximum symbols used for options.
+ */
+export abstract class ApplicationCommandNumericOptionMinMaxValueMixin {
+	/**
+	 * @internal
+	 */
+	declare protected readonly data: ApplicationCommandNumericOptionMinMaxValueData;
+
+	/**
+	 * Sets the maximum number value of this option.
+	 *
+	 * @param max - The maximum value this option can be
+	 */
+	public setMaxValue(max: number): this {
+		this.data.max_value = max;
+		return this;
+	}
+
+	/**
+	 * Removes the maximum number value of this option.
+	 */
+	public clearMaxValue(): this {
+		this.data.max_value = undefined;
+		return this;
+	}
+
+	/**
+	 * Sets the minimum number value of this option.
+	 *
+	 * @param min - The minimum value this option can be
+	 */
+	public setMinValue(min: number): this {
+		this.data.min_value = min;
+		return this;
+	}
+
+	/**
+	 * Removes the minimum number value of this option.
+	 */
+	public clearMinValue(): this {
+		this.data.min_value = undefined;
+		return this;
+	}
+}

package/src/interactions/commands/chatInput/mixins/ApplicationCommandOptionChannelTypesMixin.ts

@@ -0,0 +1,57 @@
+import { ChannelType, type APIApplicationCommandChannelOption } from 'discord-api-types/v10';
+import { normalizeArray, type RestOrArray } from '../../../../util/normalizeArray';
+
+export const ApplicationCommandOptionAllowedChannelTypes = [
+	ChannelType.GuildText,
+	ChannelType.GuildVoice,
+	ChannelType.GuildCategory,
+	ChannelType.GuildAnnouncement,
+	ChannelType.AnnouncementThread,
+	ChannelType.PublicThread,
+	ChannelType.PrivateThread,
+	ChannelType.GuildStageVoice,
+	ChannelType.GuildForum,
+	ChannelType.GuildMedia,
+] as const;
+
+/**
+ * Allowed channel types used for a channel option.
+ */
+export type ApplicationCommandOptionAllowedChannelType = (typeof ApplicationCommandOptionAllowedChannelTypes)[number];
+
+export interface ApplicationCommandOptionChannelTypesData extends Pick<
+	APIApplicationCommandChannelOption,
+	'channel_types'
+> {}
+
+/**
+ * This mixin holds channel type symbols used for options.
+ */
+export class ApplicationCommandOptionChannelTypesMixin {
+	/**
+	 * @internal
+	 */
+	declare protected readonly data: ApplicationCommandOptionChannelTypesData;
+
+	/**
+	 * Adds channel types to this option.
+	 *
+	 * @param channelTypes - The channel types
+	 */
+	public addChannelTypes(...channelTypes: RestOrArray<ApplicationCommandOptionAllowedChannelType>) {
+		this.data.channel_types ??= [];
+		this.data.channel_types.push(...normalizeArray(channelTypes));
+
+		return this;
+	}
+
+	/**
+	 * Sets the channel types for this option.
+	 *
+	 * @param channelTypes - The channel types
+	 */
+	public setChannelTypes(...channelTypes: RestOrArray<ApplicationCommandOptionAllowedChannelType>) {
+		this.data.channel_types = normalizeArray(channelTypes);
+		return this;
+	}
+}