@ovencord/builders 1.11.1

package/src/components/Components.ts

@@ -0,0 +1,275 @@
+import type {
+	APIBaseComponent,
+	APIButtonComponent,
+	APIMessageComponent,
+	APIModalComponent,
+	APISectionAccessoryComponent,
+} from 'discord-api-types/v10';
+import { ButtonStyle, ComponentType } from 'discord-api-types/v10';
+import { ActionRowBuilder } from './ActionRow.js';
+import { ComponentBuilder } from './Component.js';
+import {
+	DangerButtonBuilder,
+	PrimaryButtonBuilder,
+	SecondaryButtonBuilder,
+	SuccessButtonBuilder,
+} from './button/CustomIdButton.js';
+import { LinkButtonBuilder } from './button/LinkButton.js';
+import { PremiumButtonBuilder } from './button/PremiumButton.js';
+import { FileUploadBuilder } from './fileUpload/FileUpload.js';
+import { LabelBuilder } from './label/Label.js';
+import { ChannelSelectMenuBuilder } from './selectMenu/ChannelSelectMenu.js';
+import { MentionableSelectMenuBuilder } from './selectMenu/MentionableSelectMenu.js';
+import { RoleSelectMenuBuilder } from './selectMenu/RoleSelectMenu.js';
+import { StringSelectMenuBuilder } from './selectMenu/StringSelectMenu.js';
+import { UserSelectMenuBuilder } from './selectMenu/UserSelectMenu.js';
+import { TextInputBuilder } from './textInput/TextInput.js';
+import { ContainerBuilder } from './v2/Container.js';
+import { FileBuilder } from './v2/File.js';
+import { MediaGalleryBuilder } from './v2/MediaGallery.js';
+import { SectionBuilder } from './v2/Section.js';
+import { SeparatorBuilder } from './v2/Separator.js';
+import { TextDisplayBuilder } from './v2/TextDisplay.js';
+import { ThumbnailBuilder } from './v2/Thumbnail.js';
+
+/**
+ * The builders that may be used as top-level components on messages
+ */
+export type MessageTopLevelComponentBuilder =
+	| ActionRowBuilder
+	| ContainerBuilder
+	| FileBuilder
+	| MediaGalleryBuilder
+	| SectionBuilder
+	| SeparatorBuilder
+	| TextDisplayBuilder;
+
+/**
+ * The builders that may be used for messages.
+ */
+export type MessageComponentBuilder =
+	| MessageActionRowComponentBuilder
+	| MessageTopLevelComponentBuilder
+	| ThumbnailBuilder;
+
+/**
+ * The builders that may be used for modals.
+ */
+export type ModalComponentBuilder =
+	| ActionRowBuilder
+	| FileUploadBuilder
+	| LabelBuilder
+	| ModalActionRowComponentBuilder;
+
+/**
+ * Any button builder
+ */
+export type ButtonBuilder =
+	| DangerButtonBuilder
+	| LinkButtonBuilder
+	| PremiumButtonBuilder
+	| PrimaryButtonBuilder
+	| SecondaryButtonBuilder
+	| SuccessButtonBuilder;
+
+/**
+ * The builders that may be used within an action row for messages.
+ */
+export type MessageActionRowComponentBuilder =
+	| ButtonBuilder
+	| ChannelSelectMenuBuilder
+	| MentionableSelectMenuBuilder
+	| RoleSelectMenuBuilder
+	| StringSelectMenuBuilder
+	| UserSelectMenuBuilder;
+
+/**
+ * The builders that may be used within an action row for modals.
+ */
+export type ModalActionRowComponentBuilder = TextInputBuilder;
+
+/**
+ * Any action row component builder.
+ */
+export type AnyActionRowComponentBuilder = MessageActionRowComponentBuilder | ModalActionRowComponentBuilder;
+
+/**
+ * Any modal component builder.
+ */
+export type AnyModalComponentBuilder = FileUploadBuilder | LabelBuilder | TextDisplayBuilder;
+
+/**
+ * Components here are mapped to their respective builder.
+ */
+export interface MappedComponentTypes {
+	/**
+	 * The action row component type is associated with an {@link ActionRowBuilder}.
+	 */
+	[ComponentType.ActionRow]: ActionRowBuilder;
+	/**
+	 * The button component type is associated with a {@link BaseButtonBuilder}.
+	 */
+	[ComponentType.Button]: ButtonBuilder;
+	/**
+	 * The string select component type is associated with a {@link StringSelectMenuBuilder}.
+	 */
+	[ComponentType.StringSelect]: StringSelectMenuBuilder;
+	/**
+	 * The text input component type is associated with a {@link TextInputBuilder}.
+	 */
+	[ComponentType.TextInput]: TextInputBuilder;
+	/**
+	 * The user select component type is associated with a {@link UserSelectMenuBuilder}.
+	 */
+	[ComponentType.UserSelect]: UserSelectMenuBuilder;
+	/**
+	 * The role select component type is associated with a {@link RoleSelectMenuBuilder}.
+	 */
+	[ComponentType.RoleSelect]: RoleSelectMenuBuilder;
+	/**
+	 * The mentionable select component type is associated with a {@link MentionableSelectMenuBuilder}.
+	 */
+	[ComponentType.MentionableSelect]: MentionableSelectMenuBuilder;
+	/**
+	 * The channel select component type is associated with a {@link ChannelSelectMenuBuilder}.
+	 */
+	[ComponentType.ChannelSelect]: ChannelSelectMenuBuilder;
+	/**
+	 * The thumbnail component type is associated with a {@link ThumbnailBuilder}.
+	 */
+	[ComponentType.Thumbnail]: ThumbnailBuilder;
+	/**
+	 * The file component type is associated with a {@link FileBuilder}.
+	 */
+	[ComponentType.File]: FileBuilder;
+	/**
+	 * The separator component type is associated with a {@link SeparatorBuilder}.
+	 */
+	[ComponentType.Separator]: SeparatorBuilder;
+	/**
+	 * The text display component type is associated with a {@link TextDisplayBuilder}.
+	 */
+	[ComponentType.TextDisplay]: TextDisplayBuilder;
+	/**
+	 * The media gallery component type is associated with a {@link MediaGalleryBuilder}.
+	 */
+	[ComponentType.MediaGallery]: MediaGalleryBuilder;
+	/**
+	 * The section component type is associated with a {@link SectionBuilder}.
+	 */
+	[ComponentType.Section]: SectionBuilder;
+	/**
+	 * The container component type is associated with a {@link ContainerBuilder}.
+	 */
+	[ComponentType.Container]: ContainerBuilder;
+	/**
+	 * The label component type is associated with a {@link LabelBuilder}.
+	 */
+	[ComponentType.Label]: LabelBuilder;
+	/**
+	 * The file upload component type is associated with a {@link FileUploadBuilder}.
+	 */
+	[ComponentType.FileUpload]: FileUploadBuilder;
+}
+
+/**
+ * Factory for creating components from API data.
+ *
+ * @typeParam ComponentType - The type of component to use
+ * @param data - The API data to transform to a component class
+ */
+export function createComponentBuilder<ComponentType extends keyof MappedComponentTypes>(
+	 
+	data: (APIModalComponent | APIMessageComponent) & { type: ComponentType },
+): MappedComponentTypes[ComponentType];
+
+/**
+ * Factory for creating components from API data.
+ *
+ * @typeParam Builder - The type of component to use
+ * @param data - The API data to transform to a component class
+ */
+export function createComponentBuilder<Builder extends MessageComponentBuilder | ModalComponentBuilder>(
+	data: Builder,
+): Builder;
+
+export function createComponentBuilder(
+	data: APIMessageComponent | APIModalComponent | MessageComponentBuilder,
+): ComponentBuilder<APIBaseComponent<ComponentType>> {
+	if (data instanceof ComponentBuilder || (typeof data === 'object' && data !== null && 'toJSON' in data)) {
+		return data as any;
+	}
+
+	const rawData = data as APIMessageComponent | APIModalComponent;
+	switch (rawData.type) {
+		case ComponentType.ActionRow:
+			return new ActionRowBuilder(rawData as any);
+		case ComponentType.Button:
+			return createButtonBuilder(rawData as any) as any;
+		case ComponentType.StringSelect:
+			return new StringSelectMenuBuilder(rawData as any);
+		case ComponentType.TextInput:
+			return new TextInputBuilder(rawData as any);
+		case ComponentType.UserSelect:
+			return new UserSelectMenuBuilder(rawData as any);
+		case ComponentType.RoleSelect:
+			return new RoleSelectMenuBuilder(rawData as any);
+		case ComponentType.MentionableSelect:
+			return new MentionableSelectMenuBuilder(rawData as any);
+		case ComponentType.ChannelSelect:
+			return new ChannelSelectMenuBuilder(rawData as any);
+		case ComponentType.Thumbnail:
+			return new ThumbnailBuilder(rawData as any);
+		case ComponentType.File:
+			return new FileBuilder(rawData as any);
+		case ComponentType.Separator:
+			return new SeparatorBuilder(rawData as any);
+		case ComponentType.TextDisplay:
+			return new TextDisplayBuilder(rawData as any);
+		case ComponentType.MediaGallery:
+			return new MediaGalleryBuilder(rawData as any);
+		case ComponentType.Section:
+			return new SectionBuilder(rawData as any);
+		case ComponentType.Container:
+			return new ContainerBuilder(rawData as any);
+		case ComponentType.Label:
+			return new LabelBuilder(rawData as any);
+		case ComponentType.FileUpload:
+			return new FileUploadBuilder(rawData as any);
+		default:
+			// This case can still occur if we get a newer unsupported component type
+			throw new Error(`Cannot properly serialize component type: ${rawData.type}`);
+	}
+}
+
+function createButtonBuilder(data: APIButtonComponent): ButtonBuilder {
+	switch (data.style) {
+		case ButtonStyle.Primary:
+			return new PrimaryButtonBuilder(data);
+		case ButtonStyle.Secondary:
+			return new SecondaryButtonBuilder(data);
+		case ButtonStyle.Success:
+			return new SuccessButtonBuilder(data);
+		case ButtonStyle.Danger:
+			return new DangerButtonBuilder(data);
+		case ButtonStyle.Link:
+			return new LinkButtonBuilder(data);
+		case ButtonStyle.Premium:
+			return new PremiumButtonBuilder(data);
+		default:
+			// @ts-expect-error This case can still occur if we get a newer unsupported button style
+			throw new Error(`Cannot properly serialize button with style: ${data.style}`);
+	}
+}
+
+export function resolveAccessoryComponent(component: APISectionAccessoryComponent) {
+	switch (component.type) {
+		case ComponentType.Button:
+			return createButtonBuilder(component);
+		case ComponentType.Thumbnail:
+			return new ThumbnailBuilder(component);
+		default:
+			// @ts-expect-error This case can still occur if we get a newer unsupported component type
+			throw new Error(`Cannot properly serialize section accessory component: ${component.type}`);
+	}
+}

package/src/components/button/Button.ts

@@ -0,0 +1,34 @@
+import type { APIButtonComponent } from 'discord-api-types/v10';
+import { validate } from '../../util/validation.js';
+import { buttonPredicate } from '../Assertions.js';
+import { ComponentBuilder } from '../Component.js';
+
+/**
+ * A builder that creates API-compatible JSON data for buttons.
+ */
+export abstract class BaseButtonBuilder<ButtonData extends APIButtonComponent> extends ComponentBuilder<ButtonData> {
+	/**
+	 * @internal
+	 */
+	declare protected readonly data: Partial<ButtonData>;
+
+	/**
+	 * Sets whether this button is disabled.
+	 *
+	 * @param disabled - Whether to disable this button
+	 */
+	public setDisabled(disabled = true) {
+		this.data.disabled = disabled;
+		return this;
+	}
+
+	/**
+	 * {@inheritDoc ComponentBuilder.toJSON}
+	 */
+	public override toJSON(validationOverride?: boolean): ButtonData {
+		const clone = structuredClone(this.data);
+		validate(buttonPredicate, clone, validationOverride);
+
+		return clone as ButtonData;
+	}
+}

package/src/components/button/CustomIdButton.ts

@@ -0,0 +1,74 @@
+import { ButtonStyle, ComponentType, type APIButtonComponentWithCustomId } from 'discord-api-types/v10';
+import { Mixin } from 'ts-mixer';
+import { BaseButtonBuilder } from './Button.js';
+import { EmojiOrLabelButtonMixin } from './mixins/EmojiOrLabelButtonMixin.js';
+
+export type CustomIdButtonStyle = APIButtonComponentWithCustomId['style'];
+
+/**
+ * A builder that creates API-compatible JSON data for buttons with custom IDs.
+ *
+ * @mixes {@link BaseButtonBuilder}\<{@link discord-api-types/v10#(APIButtonComponentWithCustomId:interface)}\>
+ * @mixes {@link EmojiOrLabelButtonMixin}
+ */
+export interface CustomIdButtonBuilder extends BaseButtonBuilder<APIButtonComponentWithCustomId>, EmojiOrLabelButtonMixin {}
+
+export abstract class CustomIdButtonBuilder extends Mixin(
+	BaseButtonBuilder<APIButtonComponentWithCustomId>,
+	EmojiOrLabelButtonMixin,
+) {
+	protected override readonly data: Partial<APIButtonComponentWithCustomId>;
+
+	protected constructor(data: Partial<APIButtonComponentWithCustomId> = {}) {
+		super();
+		this.data = { ...structuredClone(data), type: ComponentType.Button };
+	}
+
+	/**
+	 * Sets the custom id for this button.
+	 *
+	 * @remarks
+	 * This method is only applicable to buttons that are not using the `Link` button style.
+	 * @param customId - The custom id to use
+	 */
+	public setCustomId(customId: string) {
+		this.data.custom_id = customId;
+		return this;
+	}
+}
+
+/**
+ * A builder that creates API-compatible JSON data for buttons with custom IDs (using the primary style).
+ */
+export class PrimaryButtonBuilder extends CustomIdButtonBuilder {
+	public constructor(data: Partial<APIButtonComponentWithCustomId> = {}) {
+		super({ ...data, style: ButtonStyle.Primary });
+	}
+}
+
+/**
+ * A builder that creates API-compatible JSON data for buttons with custom IDs (using the secondary style).
+ */
+export class SecondaryButtonBuilder extends CustomIdButtonBuilder {
+	public constructor(data: Partial<APIButtonComponentWithCustomId> = {}) {
+		super({ ...data, style: ButtonStyle.Secondary });
+	}
+}
+
+/**
+ * A builder that creates API-compatible JSON data for buttons with custom IDs (using the success style).
+ */
+export class SuccessButtonBuilder extends CustomIdButtonBuilder {
+	public constructor(data: Partial<APIButtonComponentWithCustomId> = {}) {
+		super({ ...data, style: ButtonStyle.Success });
+	}
+}
+
+/**
+ * A builder that creates API-compatible JSON data for buttons with custom IDs (using the danger style).
+ */
+export class DangerButtonBuilder extends CustomIdButtonBuilder {
+	public constructor(data: Partial<APIButtonComponentWithCustomId> = {}) {
+		super({ ...data, style: ButtonStyle.Danger });
+	}
+}

package/src/components/button/LinkButton.ts

@@ -0,0 +1,39 @@
+import {
+	ButtonStyle,
+	ComponentType,
+	type APIButtonComponent,
+	type APIButtonComponentWithURL,
+} from 'discord-api-types/v10';
+import { Mixin } from 'ts-mixer';
+import { BaseButtonBuilder } from './Button.js';
+import { EmojiOrLabelButtonMixin } from './mixins/EmojiOrLabelButtonMixin.js';
+
+/**
+ * A builder that creates API-compatible JSON data for buttons with links.
+ *
+ * @mixes {@link BaseButtonBuilder}\<{@link discord-api-types/v10#(APIButtonComponentWithURL:interface)}\>
+ * @mixes {@link EmojiOrLabelButtonMixin}
+ */
+export interface LinkButtonBuilder extends BaseButtonBuilder<APIButtonComponentWithURL>, EmojiOrLabelButtonMixin {}
+
+export class LinkButtonBuilder extends Mixin(BaseButtonBuilder<APIButtonComponentWithURL>, EmojiOrLabelButtonMixin) {
+	protected override readonly data: Partial<APIButtonComponentWithURL>;
+
+	public constructor(data: Partial<APIButtonComponent> = {}) {
+		super();
+		this.data = { ...structuredClone(data), type: ComponentType.Button, style: ButtonStyle.Link };
+	}
+
+	/**
+	 * Sets the URL for this button.
+	 *
+	 * @remarks
+	 * This method is only available to buttons using the `Link` button style.
+	 * Only three types of URL schemes are currently supported: `https://`, `http://`, and `discord://`.
+	 * @param url - The URL to use
+	 */
+	public setURL(url: string) {
+		this.data.url = url;
+		return this;
+	}
+}

package/src/components/button/PremiumButton.ts

@@ -0,0 +1,26 @@
+import type { APIButtonComponentWithSKUId, Snowflake } from 'discord-api-types/v10';
+import { ButtonStyle, ComponentType } from 'discord-api-types/v10';
+import { BaseButtonBuilder } from './Button.js';
+
+/**
+ * A builder that creates API-compatible JSON data for premium buttons.
+ */
+export class PremiumButtonBuilder extends BaseButtonBuilder<APIButtonComponentWithSKUId> {
+	protected override readonly data: Partial<APIButtonComponentWithSKUId>;
+
+	public constructor(data: Partial<APIButtonComponentWithSKUId> = {}) {
+		super();
+		this.data = { ...structuredClone(data), type: ComponentType.Button, style: ButtonStyle.Premium };
+	}
+
+	/**
+	 * Sets the SKU id that represents a purchasable SKU for this button.
+	 *
+	 * @remarks Only available when using premium-style buttons.
+	 * @param skuId - The SKU id to use
+	 */
+	public setSKUId(skuId: Snowflake) {
+		this.data.sku_id = skuId;
+		return this;
+	}
+}

package/src/components/button/mixins/EmojiOrLabelButtonMixin.ts

@@ -0,0 +1,52 @@
+import type { APIButtonComponent, APIButtonComponentWithSKUId, APIMessageComponentEmoji } from 'discord-api-types/v10';
+
+export interface EmojiOrLabelButtonData extends Pick<
+	Exclude<APIButtonComponent, APIButtonComponentWithSKUId>,
+	'emoji' | 'label'
+> {}
+
+/**
+ * A mixin that adds emoji and label symbols to a button builder.
+ */
+export class EmojiOrLabelButtonMixin {
+	/**
+	 * @internal
+	 */
+	declare protected readonly data: EmojiOrLabelButtonData;
+
+	/**
+	 * Sets the emoji to display on this button.
+	 *
+	 * @param emoji - The emoji to use
+	 */
+	public setEmoji(emoji: APIMessageComponentEmoji) {
+		this.data.emoji = emoji;
+		return this;
+	}
+
+	/**
+	 * Clears the emoji on this button.
+	 */
+	public clearEmoji() {
+		this.data.emoji = undefined;
+		return this;
+	}
+
+	/**
+	 * Sets the label for this button.
+	 *
+	 * @param label - The label to use
+	 */
+	public setLabel(label: string) {
+		this.data.label = label;
+		return this;
+	}
+
+	/**
+	 * Clears the label on this button.
+	 */
+	public clearLabel() {
+		this.data.label = undefined;
+		return this;
+	}
+}

package/src/components/fileUpload/Assertions.ts

@@ -0,0 +1,12 @@
+import { ComponentType } from 'discord-api-types/v10';
+import { z } from 'zod';
+import { customIdPredicate, idPredicate } from '../../Assertions';
+
+export const fileUploadPredicate = z.object({
+	type: z.literal(ComponentType.FileUpload),
+	id: idPredicate,
+	custom_id: customIdPredicate,
+	min_values: z.number().int().min(0).max(10).optional(),
+	max_values: z.number().int().min(1).max(10).optional(),
+	required: z.boolean().optional(),
+});

package/src/components/fileUpload/FileUpload.ts

@@ -0,0 +1,109 @@
+import type { APIFileUploadComponent } from 'discord-api-types/v10';
+import { ComponentType } from 'discord-api-types/v10';
+import { validate } from '../../util/validation.js';
+import { ComponentBuilder } from '../Component.js';
+import { fileUploadPredicate } from './Assertions.js';
+
+/**
+ * A builder that creates API-compatible JSON data for file uploads.
+ */
+export class FileUploadBuilder extends ComponentBuilder<APIFileUploadComponent> {
+	/**
+	 * @internal
+	 */
+	protected readonly data: Partial<APIFileUploadComponent>;
+
+	/**
+	 * Creates a new file upload.
+	 *
+	 * @param data - The API data to create this file upload with
+	 * @example
+	 * Creating a file upload from an API data object:
+	 * ```ts
+	 * const fileUpload = new FileUploadBuilder({
+	 * 	custom_id: "file_upload",
+	 *  min_values: 2,
+	 *  max_values: 5,
+	 * });
+	 * ```
+	 * @example
+	 * Creating a file upload using setters and API data:
+	 * ```ts
+	 * const fileUpload = new FileUploadBuilder({
+	 * 	custom_id: "file_upload",
+	 *  min_values: 2,
+	 *  max_values: 5,
+	 * }).setRequired();
+	 * ```
+	 */
+	public constructor(data: Partial<APIFileUploadComponent> = {}) {
+		super();
+		this.data = { ...structuredClone(data), type: ComponentType.FileUpload };
+	}
+
+	/**
+	 * Sets the custom id for this file upload.
+	 *
+	 * @param customId - The custom id to use
+	 */
+	public setCustomId(customId: string) {
+		this.data.custom_id = customId;
+		return this;
+	}
+
+	/**
+	 * Sets the minimum number of file uploads required.
+	 *
+	 * @param minValues - The minimum values that must be uploaded
+	 */
+	public setMinValues(minValues: number) {
+		this.data.min_values = minValues;
+		return this;
+	}
+
+	/**
+	 * Clears the minimum values.
+	 */
+	public clearMinValues() {
+		this.data.min_values = undefined;
+		return this;
+	}
+
+	/**
+	 * Sets the maximum number of file uploads required.
+	 *
+	 * @param maxValues - The maximum values that can be uploaded
+	 */
+	public setMaxValues(maxValues: number) {
+		this.data.max_values = maxValues;
+		return this;
+	}
+
+	/**
+	 * Clears the maximum values.
+	 */
+	public clearMaxValues() {
+		this.data.max_values = undefined;
+		return this;
+	}
+
+	/**
+	 * Sets whether this file upload is required.
+	 *
+	 * @param required - Whether this file upload is required
+	 */
+	public setRequired(required = true) {
+		this.data.required = required;
+		return this;
+	}
+
+	/**
+	 * {@inheritDoc ComponentBuilder.toJSON}
+	 */
+	public toJSON(validationOverride?: boolean): APIFileUploadComponent {
+		const clone = structuredClone(this.data);
+		validate(fileUploadPredicate, clone, validationOverride);
+
+		return clone as APIFileUploadComponent;
+	}
+}

package/src/components/label/Assertions.ts

@@ -0,0 +1,28 @@
+import { ComponentType } from 'discord-api-types/v10';
+import { z } from 'zod';
+import { idPredicate } from '../../Assertions';
+import {
+	selectMenuChannelPredicate,
+	selectMenuMentionablePredicate,
+	selectMenuRolePredicate,
+	selectMenuStringPredicate,
+	selectMenuUserPredicate,
+} from '../Assertions';
+import { fileUploadPredicate } from '../fileUpload/Assertions';
+import { textInputPredicate } from '../textInput/Assertions';
+
+export const labelPredicate = z.object({
+	id: idPredicate,
+	type: z.literal(ComponentType.Label),
+	label: z.string().min(1).max(45),
+	description: z.string().min(1).max(100).optional(),
+	component: z.union([
+		selectMenuStringPredicate,
+		textInputPredicate,
+		selectMenuUserPredicate,
+		selectMenuRolePredicate,
+		selectMenuMentionablePredicate,
+		selectMenuChannelPredicate,
+		fileUploadPredicate,
+	]),
+});