@ovencord/builders 1.11.1

package/src/components/ActionRow.ts

@@ -0,0 +1,346 @@
+import type {
+	APITextInputComponent,
+	APIActionRowComponent,
+	APIComponentInActionRow,
+	APIChannelSelectComponent,
+	APIMentionableSelectComponent,
+	APIRoleSelectComponent,
+	APIStringSelectComponent,
+	APIUserSelectComponent,
+	APIButtonComponentWithCustomId,
+	APIButtonComponentWithSKUId,
+	APIButtonComponentWithURL,
+} from 'discord-api-types/v10';
+import { ComponentType } from 'discord-api-types/v10';
+import { normalizeArray, type RestOrArray } from '../util/normalizeArray.js';
+import { resolveBuilder } from '../util/resolveBuilder.js';
+import { validate } from '../util/validation.js';
+import { actionRowPredicate } from './Assertions.js';
+import { ComponentBuilder } from './Component.js';
+import type { AnyActionRowComponentBuilder } from './Components.js';
+import { createComponentBuilder } from './Components.js';
+import {
+	DangerButtonBuilder,
+	PrimaryButtonBuilder,
+	SecondaryButtonBuilder,
+	SuccessButtonBuilder,
+} from './button/CustomIdButton.js';
+import { LinkButtonBuilder } from './button/LinkButton.js';
+import { PremiumButtonBuilder } from './button/PremiumButton.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';
+
+export interface ActionRowBuilderData extends Partial<
+	Omit<APIActionRowComponent<APIComponentInActionRow>, 'components'>
+> {
+	components: AnyActionRowComponentBuilder[];
+}
+
+/**
+ * A builder that creates API-compatible JSON data for action rows.
+ */
+export class ActionRowBuilder extends ComponentBuilder<APIActionRowComponent<APIComponentInActionRow>> {
+	/**
+	 * @internal
+	 */
+	protected readonly data: ActionRowBuilderData;
+
+	/**
+	 * The components within this action row.
+	 */
+	public get components(): readonly AnyActionRowComponentBuilder[] {
+		return this.data.components;
+	}
+
+	/**
+	 * Creates a new action row.
+	 *
+	 * @param data - The API data to create this action row with
+	 * @example
+	 * Creating an action row from an API data object:
+	 * ```ts
+	 * const actionRow = new ActionRowBuilder({
+	 * 	components: [
+	 * 		{
+	 * 			custom_id: "custom id",
+	 * 			label: "Type something",
+	 * 			style: TextInputStyle.Short,
+	 * 			type: ComponentType.TextInput,
+	 * 		},
+	 * 	],
+	 * });
+	 * ```
+	 * @example
+	 * Creating an action row using setters and API data:
+	 * ```ts
+	 * const actionRow = new ActionRowBuilder({
+	 * 	components: [
+	 * 		{
+	 * 			custom_id: "custom id",
+	 * 			label: "Click me",
+	 * 			style: ButtonStyle.Primary,
+	 * 			type: ComponentType.Button,
+	 * 		},
+	 * 	],
+	 * })
+	 * 	.addComponents(button2, button3);
+	 * ```
+	 */
+	public constructor(data: Partial<APIActionRowComponent<APIComponentInActionRow>> = {}) {
+		super();
+
+		const { components = [], ...rest } = data;
+
+		this.data = {
+			...structuredClone(rest),
+			components: components.map((component) => createComponentBuilder(component)),
+			type: ComponentType.ActionRow,
+		};
+	}
+
+	/**
+	 * Adds primary button components to this action row.
+	 *
+	 * @param input - The buttons to add
+	 */
+	public addPrimaryButtonComponents(
+		...input: RestOrArray<
+			APIButtonComponentWithCustomId | PrimaryButtonBuilder | ((builder: PrimaryButtonBuilder) => PrimaryButtonBuilder)
+		>
+	): this {
+		const normalized = normalizeArray(input);
+		const resolved = normalized.map((component) => resolveBuilder(component, PrimaryButtonBuilder));
+
+		this.data.components.push(...resolved);
+		return this;
+	}
+
+	/**
+	 * Adds secondary button components to this action row.
+	 *
+	 * @param input - The buttons to add
+	 */
+	public addSecondaryButtonComponents(
+		...input: RestOrArray<
+			| APIButtonComponentWithCustomId
+			| SecondaryButtonBuilder
+			| ((builder: SecondaryButtonBuilder) => SecondaryButtonBuilder)
+		>
+	): this {
+		const normalized = normalizeArray(input);
+		const resolved = normalized.map((component) => resolveBuilder(component, SecondaryButtonBuilder));
+
+		this.data.components.push(...resolved);
+		return this;
+	}
+
+	/**
+	 * Adds success button components to this action row.
+	 *
+	 * @param input - The buttons to add
+	 */
+	public addSuccessButtonComponents(
+		...input: RestOrArray<
+			APIButtonComponentWithCustomId | SuccessButtonBuilder | ((builder: SuccessButtonBuilder) => SuccessButtonBuilder)
+		>
+	): this {
+		const normalized = normalizeArray(input);
+		const resolved = normalized.map((component) => resolveBuilder(component, SuccessButtonBuilder));
+
+		this.data.components.push(...resolved);
+		return this;
+	}
+
+	/**
+	 * Adds danger button components to this action row.
+	 */
+	public addDangerButtonComponents(
+		...input: RestOrArray<
+			APIButtonComponentWithCustomId | DangerButtonBuilder | ((builder: DangerButtonBuilder) => DangerButtonBuilder)
+		>
+	): this {
+		const normalized = normalizeArray(input);
+		const resolved = normalized.map((component) => resolveBuilder(component, DangerButtonBuilder));
+
+		this.data.components.push(...resolved);
+		return this;
+	}
+
+	/**
+	 * Generically add any type of component to this action row, only takes in an instance of a component builder.
+	 */
+	public addComponents(...input: RestOrArray<AnyActionRowComponentBuilder>): this {
+		const normalized = normalizeArray(input);
+		this.data.components.push(...normalized);
+
+		return this;
+	}
+
+	/**
+	 * Adds SKU id button components to this action row.
+	 *
+	 * @param input - The buttons to add
+	 */
+	public addPremiumButtonComponents(
+		...input: RestOrArray<
+			APIButtonComponentWithSKUId | PremiumButtonBuilder | ((builder: PremiumButtonBuilder) => PremiumButtonBuilder)
+		>
+	): this {
+		const normalized = normalizeArray(input);
+		const resolved = normalized.map((component) => resolveBuilder(component, PremiumButtonBuilder));
+
+		this.data.components.push(...resolved);
+		return this;
+	}
+
+	/**
+	 * Adds URL button components to this action row.
+	 *
+	 * @param input - The buttons to add
+	 */
+	public addLinkButtonComponents(
+		...input: RestOrArray<
+			APIButtonComponentWithURL | LinkButtonBuilder | ((builder: LinkButtonBuilder) => LinkButtonBuilder)
+		>
+	): this {
+		const normalized = normalizeArray(input);
+		const resolved = normalized.map((component) => resolveBuilder(component, LinkButtonBuilder));
+
+		this.data.components.push(...resolved);
+		return this;
+	}
+
+	/**
+	 * Adds a channel select menu component to this action row.
+	 *
+	 * @param input - A function that returns a component builder or an already built builder
+	 */
+	public addChannelSelectMenuComponent(
+		input:
+			| APIChannelSelectComponent
+			| ChannelSelectMenuBuilder
+			| ((builder: ChannelSelectMenuBuilder) => ChannelSelectMenuBuilder),
+	): this {
+		this.data.components.push(resolveBuilder(input, ChannelSelectMenuBuilder));
+		return this;
+	}
+
+	/**
+	 * Adds a mentionable select menu component to this action row.
+	 *
+	 * @param input - A function that returns a component builder or an already built builder
+	 */
+	public addMentionableSelectMenuComponent(
+		input:
+			| APIMentionableSelectComponent
+			| MentionableSelectMenuBuilder
+			| ((builder: MentionableSelectMenuBuilder) => MentionableSelectMenuBuilder),
+	): this {
+		this.data.components.push(resolveBuilder(input, MentionableSelectMenuBuilder));
+		return this;
+	}
+
+	/**
+	 * Adds a role select menu component to this action row.
+	 *
+	 * @param input - A function that returns a component builder or an already built builder
+	 */
+	public addRoleSelectMenuComponent(
+		input: APIRoleSelectComponent | RoleSelectMenuBuilder | ((builder: RoleSelectMenuBuilder) => RoleSelectMenuBuilder),
+	): this {
+		this.data.components.push(resolveBuilder(input, RoleSelectMenuBuilder));
+		return this;
+	}
+
+	/**
+	 * Adds a string select menu component to this action row.
+	 *
+	 * @param input - A function that returns a component builder or an already built builder
+	 */
+	public addStringSelectMenuComponent(
+		input:
+			| APIStringSelectComponent
+			| StringSelectMenuBuilder
+			| ((builder: StringSelectMenuBuilder) => StringSelectMenuBuilder),
+	): this {
+		this.data.components.push(resolveBuilder(input, StringSelectMenuBuilder));
+		return this;
+	}
+
+	/**
+	 * Adds a user select menu component to this action row.
+	 *
+	 * @param input - A function that returns a component builder or an already built builder
+	 */
+	public addUserSelectMenuComponent(
+		input: APIUserSelectComponent | UserSelectMenuBuilder | ((builder: UserSelectMenuBuilder) => UserSelectMenuBuilder),
+	): this {
+		this.data.components.push(resolveBuilder(input, UserSelectMenuBuilder));
+		return this;
+	}
+
+	/**
+	 * Adds a text input component to this action row.
+	 *
+	 * @param input - A function that returns a component builder or an already built builder
+	 */
+	public addTextInputComponent(
+		input: APITextInputComponent | TextInputBuilder | ((builder: TextInputBuilder) => TextInputBuilder),
+	): this {
+		this.data.components.push(resolveBuilder(input, TextInputBuilder));
+		return this;
+	}
+
+	/**
+	 * Removes, replaces, or inserts components for this action row.
+	 *
+	 * @remarks
+	 * This method behaves similarly
+	 * to {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array/splice | Array.prototype.splice()}.
+	 *
+	 * It's useful for modifying and adjusting order of the already-existing components of an action row.
+	 * @example
+	 * Remove the first component:
+	 * ```ts
+	 * actionRow.spliceComponents(0, 1);
+	 * ```
+	 * @example
+	 * Remove the first n components:
+	 * ```ts
+	 * const n = 4;
+	 * actionRow.spliceComponents(0, n);
+	 * ```
+	 * @example
+	 * Remove the last component:
+	 * ```ts
+	 * actionRow.spliceComponents(-1, 1);
+	 * ```
+	 * @param index - The index to start at
+	 * @param deleteCount - The number of components to remove
+	 * @param components - The replacing component objects
+	 */
+	public spliceComponents(index: number, deleteCount: number, ...components: AnyActionRowComponentBuilder[]): this {
+		this.data.components.splice(index, deleteCount, ...components);
+		return this;
+	}
+
+	/**
+	 * {@inheritDoc ComponentBuilder.toJSON}
+	 */
+	public override toJSON(validationOverride?: boolean): APIActionRowComponent<APIComponentInActionRow> {
+		const { components, ...rest } = this.data;
+
+		const data = {
+			...structuredClone(rest),
+			components: components.map((component) => (component as any).toJSON(validationOverride)),
+		};
+
+		validate(actionRowPredicate, data, validationOverride);
+
+		return data as APIActionRowComponent<APIComponentInActionRow>;
+	}
+}

package/src/components/Assertions.ts

@@ -0,0 +1,190 @@
+import { ButtonStyle, ChannelType, ComponentType, SelectMenuDefaultValueType } from 'discord-api-types/v10';
+import { z } from 'zod';
+import { idPredicate, customIdPredicate, snowflakePredicate } from '../Assertions.js';
+
+export const emojiPredicate = z
+	.strictObject({
+		id: snowflakePredicate.optional(),
+		name: z.string().min(1).max(32).optional(),
+		animated: z.boolean().optional(),
+	})
+	.refine((data) => data.id !== undefined || data.name !== undefined, {
+		message: "Either 'id' or 'name' must be provided",
+	});
+
+const buttonPredicateBase = z.strictObject({
+	type: z.literal(ComponentType.Button),
+	disabled: z.boolean().optional(),
+});
+
+const buttonLabelPredicate = z.string().min(1).max(80);
+
+const buttonCustomIdPredicateBase = buttonPredicateBase
+	.extend({
+		custom_id: customIdPredicate,
+		emoji: emojiPredicate.optional(),
+		label: buttonLabelPredicate.optional(),
+	});
+
+
+
+const buttonPrimaryPredicate = buttonCustomIdPredicateBase.extend({ style: z.literal(ButtonStyle.Primary) });
+const buttonSecondaryPredicate = buttonCustomIdPredicateBase.extend({ style: z.literal(ButtonStyle.Secondary) });
+const buttonSuccessPredicate = buttonCustomIdPredicateBase.extend({ style: z.literal(ButtonStyle.Success) });
+const buttonDangerPredicate = buttonCustomIdPredicateBase.extend({ style: z.literal(ButtonStyle.Danger) });
+
+const buttonPrimaryRefinedPredicate = buttonPrimaryPredicate.refine((data) => data.emoji !== undefined || data.label !== undefined, {
+	message: 'Buttons with a custom id must have either an emoji or a label.',
+});
+const buttonSecondaryRefinedPredicate = buttonSecondaryPredicate.refine((data) => data.emoji !== undefined || data.label !== undefined, {
+	message: 'Buttons with a custom id must have either an emoji or a label.',
+});
+const buttonSuccessRefinedPredicate = buttonSuccessPredicate.refine((data) => data.emoji !== undefined || data.label !== undefined, {
+	message: 'Buttons with a custom id must have either an emoji or a label.',
+});
+const buttonDangerRefinedPredicate = buttonDangerPredicate.refine((data) => data.emoji !== undefined || data.label !== undefined, {
+	message: 'Buttons with a custom id must have either an emoji or a label.',
+});
+
+const buttonLinkPredicate = buttonPredicateBase
+	.extend({
+		style: z.literal(ButtonStyle.Link),
+		url: z.string().url().max(512).refine((url) => url.startsWith('http:') || url.startsWith('https:') || url.startsWith('discord:'), { message: 'URL must use http, https, or discord protocol' }),
+		emoji: emojiPredicate.optional(),
+		label: buttonLabelPredicate.optional(),
+	})
+	.refine((data) => data.emoji !== undefined || data.label !== undefined, {
+		message: 'Link buttons must have either an emoji or a label.',
+	});
+
+const buttonPremiumPredicate = buttonPredicateBase.extend({
+	style: z.literal(ButtonStyle.Premium),
+	sku_id: snowflakePredicate,
+});
+
+export const buttonPredicate = z.union([
+	buttonLinkPredicate,
+	buttonPrimaryRefinedPredicate,
+	buttonSecondaryRefinedPredicate,
+	buttonSuccessRefinedPredicate,
+	buttonDangerRefinedPredicate,
+	buttonPremiumPredicate,
+]);
+
+const selectMenuBasePredicate = z.object({
+	id: idPredicate,
+	placeholder: z.string().max(150).optional(),
+	min_values: z.number().min(0).max(25).optional(),
+	max_values: z.number().min(0).max(25).optional(),
+	custom_id: customIdPredicate,
+	disabled: z.boolean().optional(),
+});
+
+export const selectMenuChannelPredicate = selectMenuBasePredicate.extend({
+	type: z.literal(ComponentType.ChannelSelect),
+	channel_types: z.nativeEnum(ChannelType).array().optional(),
+	default_values: z
+		.object({ id: snowflakePredicate, type: z.literal(SelectMenuDefaultValueType.Channel) })
+		.array()
+		.max(25)
+		.optional(),
+});
+
+export const selectMenuMentionablePredicate = selectMenuBasePredicate.extend({
+	type: z.literal(ComponentType.MentionableSelect),
+	default_values: z
+		.object({
+			id: snowflakePredicate,
+			type: z.union([z.literal(SelectMenuDefaultValueType.Role), z.literal(SelectMenuDefaultValueType.User)]),
+		})
+		.array()
+		.max(25)
+		.optional(),
+});
+
+export const selectMenuRolePredicate = selectMenuBasePredicate.extend({
+	type: z.literal(ComponentType.RoleSelect),
+	default_values: z
+		.object({ id: snowflakePredicate, type: z.literal(SelectMenuDefaultValueType.Role) })
+		.array()
+		.max(25)
+		.optional(),
+});
+
+export const selectMenuStringOptionPredicate = z.object({
+	label: z.string().min(1).max(100),
+	value: z.string().min(1).max(100),
+	description: z.string().min(1).max(100).optional(),
+	emoji: emojiPredicate.optional(),
+	default: z.boolean().optional(),
+});
+
+export const selectMenuStringPredicate = selectMenuBasePredicate
+	.extend({
+		type: z.literal(ComponentType.StringSelect),
+		options: selectMenuStringOptionPredicate.array().min(1).max(25),
+	})
+	.superRefine((value, ctx) => {
+		const addIssue = (name: string, minimum: number) =>
+			ctx.addIssue({
+				code: z.ZodIssueCode.too_small,
+				message: `The number of options must be greater than or equal to ${name}`,
+				inclusive: true,
+				minimum,
+				type: 'array',
+				path: ['options'],
+			});
+
+		if (value.min_values !== undefined && value.options.length < value.min_values) {
+			addIssue('min_values', value.min_values);
+		}
+
+		if (
+			value.min_values !== undefined &&
+			value.max_values !== undefined &&
+			value.min_values > value.max_values
+		) {
+			ctx.addIssue({
+				code: z.ZodIssueCode.too_big,
+				message: `The maximum amount of options must be greater than or equal to the minimum amount of options`,
+				inclusive: true,
+				maximum: value.max_values,
+				type: 'number',
+				path: ['min_values'],
+			});
+		}
+	});
+
+export const selectMenuUserPredicate = selectMenuBasePredicate.extend({
+	type: z.literal(ComponentType.UserSelect),
+	default_values: z
+		.object({ id: snowflakePredicate, type: z.literal(SelectMenuDefaultValueType.User) })
+		.array()
+		.max(25)
+		.optional(),
+});
+
+export const actionRowPredicate = z.object({
+	id: idPredicate,
+	type: z.literal(ComponentType.ActionRow),
+	components: z.union([
+		z
+			.object({ type: z.literal(ComponentType.Button) })
+			.array()
+			.min(1)
+			.max(5),
+		z
+			.object({
+				type: z.union([
+					z.literal(ComponentType.ChannelSelect),
+					z.literal(ComponentType.MentionableSelect),
+					z.literal(ComponentType.StringSelect),
+					z.literal(ComponentType.RoleSelect),
+					z.literal(ComponentType.TextInput),
+					z.literal(ComponentType.UserSelect),
+				]),
+			})
+			.array()
+			.length(1),
+	]),
+});

package/src/components/Component.ts

@@ -0,0 +1,47 @@
+import type { JSONEncodable } from '@ovencord/util';
+import type { APIBaseComponent, ComponentType } from 'discord-api-types/v10';
+
+export interface ComponentBuilderBaseData {
+	id?: number | undefined;
+}
+
+/**
+ * The base component builder that contains common symbols for all sorts of components.
+ *
+ * @typeParam Component - The type of API data that is stored within the builder
+ */
+export abstract class ComponentBuilder<
+	Component extends APIBaseComponent<ComponentType>,
+> implements JSONEncodable<Component> {
+	/**
+	 * @internal
+	 */
+	protected abstract readonly data: ComponentBuilderBaseData;
+
+	/**
+	 * Sets the id of this component.
+	 *
+	 * @param id - The id to use
+	 */
+	public setId(id: number) {
+		this.data.id = id;
+		return this;
+	}
+
+	/**
+	 * Clears the id of this component, defaulting to a default incremented id.
+	 */
+	public clearId() {
+		this.data.id = undefined;
+		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): Component;
+}