@ovencord/builders 1.11.1

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

@@ -0,0 +1,31 @@
+import { ApplicationCommandType, ApplicationIntegrationType, InteractionContextType } from 'discord-api-types/v10';
+import { z } from 'zod';
+import { localeMapPredicate, memberPermissionsPredicate } from '../../../Assertions.js';
+
+const namePredicate = z
+	.string()
+	.min(1)
+	.max(32)
+	.refine((val) => val.trim().length > 0, {
+		message: 'Must not consist of only whitespace.',
+	});
+
+const contextsPredicate = z.array(z.nativeEnum(InteractionContextType));
+const integrationTypesPredicate = z.array(z.nativeEnum(ApplicationIntegrationType));
+
+const baseContextMenuCommandPredicate = z.object({
+	contexts: contextsPredicate.optional(),
+	default_member_permissions: memberPermissionsPredicate.optional(),
+	name: namePredicate,
+	name_localizations: localeMapPredicate.optional(),
+	integration_types: integrationTypesPredicate.optional(),
+	nsfw: z.boolean().optional(),
+});
+
+export const userCommandPredicate = baseContextMenuCommandPredicate.extend({
+	type: z.literal(ApplicationCommandType.User),
+});
+
+export const messageCommandPredicate = baseContextMenuCommandPredicate.extend({
+	type: z.literal(ApplicationCommandType.Message),
+});

package/src/interactions/commands/contextMenu/ContextMenuCommand.ts

@@ -0,0 +1,42 @@
+import type { ApplicationCommandType, RESTPostAPIContextMenuApplicationCommandsJSONBody } from 'discord-api-types/v10';
+import { Mixin } from 'ts-mixer';
+import { CommandBuilder } from '../Command.js';
+import { SharedName } from '../SharedName.js';
+
+/**
+ * The type a context menu command can be.
+ */
+export type ContextMenuCommandType = ApplicationCommandType.Message | ApplicationCommandType.User;
+
+/**
+ * A builder that creates API-compatible JSON data for context menu commands.
+ *
+ * @mixes {@link CommandBuilder}\<{@link discord-api-types/v10#(RESTPostAPIContextMenuApplicationCommandsJSONBody:interface)}\>
+ * @mixes {@link SharedName}
+ */
+export abstract class ContextMenuCommandBuilder extends Mixin(
+	CommandBuilder<RESTPostAPIContextMenuApplicationCommandsJSONBody>,
+	SharedName,
+) {
+	/**
+	 * The API data associated with this context menu command.
+	 *
+	 * @internal
+	 */
+	protected override readonly data: Partial<RESTPostAPIContextMenuApplicationCommandsJSONBody>;
+
+	/**
+	 * Creates a new context menu command.
+	 *
+	 * @param data - The API data to create this context menu command with
+	 */
+	public constructor(data: Partial<RESTPostAPIContextMenuApplicationCommandsJSONBody> = {}) {
+		super();
+		this.data = structuredClone(data);
+	}
+
+	/**
+	 * {@inheritDoc CommandBuilder.toJSON}
+	 */
+	public abstract override toJSON(validationOverride?: boolean): RESTPostAPIContextMenuApplicationCommandsJSONBody;
+}

package/src/interactions/commands/contextMenu/MessageCommand.ts

@@ -0,0 +1,19 @@
+import { ApplicationCommandType, type RESTPostAPIContextMenuApplicationCommandsJSONBody } from 'discord-api-types/v10';
+import { validate } from '../../../util/validation.js';
+import { messageCommandPredicate } from './Assertions.js';
+import { ContextMenuCommandBuilder } from './ContextMenuCommand.js';
+
+/**
+ * A builder that creates API-compatible JSON data for message context menu commands.
+ */
+export class MessageContextCommandBuilder extends ContextMenuCommandBuilder {
+	/**
+	 * {@inheritDoc CommandBuilder.toJSON}
+	 */
+	public override toJSON(validationOverride?: boolean): RESTPostAPIContextMenuApplicationCommandsJSONBody {
+		const data = { ...structuredClone(this.data), type: ApplicationCommandType.Message };
+		validate(messageCommandPredicate, data, validationOverride);
+
+		return data as RESTPostAPIContextMenuApplicationCommandsJSONBody;
+	}
+}

package/src/interactions/commands/contextMenu/UserCommand.ts

@@ -0,0 +1,19 @@
+import { ApplicationCommandType, type RESTPostAPIContextMenuApplicationCommandsJSONBody } from 'discord-api-types/v10';
+import { validate } from '../../../util/validation.js';
+import { userCommandPredicate } from './Assertions.js';
+import { ContextMenuCommandBuilder } from './ContextMenuCommand.js';
+
+/**
+ * A builder that creates API-compatible JSON data for user context menu commands.
+ */
+export class UserContextCommandBuilder extends ContextMenuCommandBuilder {
+	/**
+	 * {@inheritDoc CommandBuilder.toJSON}
+	 */
+	public override toJSON(validationOverride?: boolean): RESTPostAPIContextMenuApplicationCommandsJSONBody {
+		const data = { ...structuredClone(this.data), type: ApplicationCommandType.User };
+		validate(userCommandPredicate, data, validationOverride);
+
+		return data as RESTPostAPIContextMenuApplicationCommandsJSONBody;
+	}
+}

package/src/interactions/modals/Assertions.ts

@@ -0,0 +1,27 @@
+import { ComponentType } from 'discord-api-types/v10';
+import { z } from 'zod';
+import { customIdPredicate } from '../../Assertions.js';
+import { labelPredicate } from '../../components/label/Assertions.js';
+import { textDisplayPredicate } from '../../components/v2/Assertions.js';
+
+const titlePredicate = z.string().min(1).max(45);
+
+export const modalPredicate = z.object({
+	title: titlePredicate,
+	custom_id: customIdPredicate,
+	components: z
+		.union([
+			z.object({
+				type: z.literal(ComponentType.ActionRow),
+				components: z
+					.object({ type: z.literal(ComponentType.TextInput) })
+					.array()
+					.length(1),
+			}),
+			labelPredicate,
+			textDisplayPredicate,
+		])
+		.array()
+		.min(1)
+		.max(5),
+});

package/src/interactions/modals/Modal.ts

@@ -0,0 +1,158 @@
+import type { JSONEncodable } from '@ovencord/util';
+import type {
+	APILabelComponent,
+	APIModalInteractionResponseCallbackData,
+	APITextDisplayComponent,
+} from 'discord-api-types/v10';
+import type { ActionRowBuilder } from '../../components/ActionRow.js';
+import type { AnyModalComponentBuilder } from '../../components/Components.js';
+import { createComponentBuilder } from '../../components/Components.js';
+import { LabelBuilder } from '../../components/label/Label.js';
+import { TextDisplayBuilder } from '../../components/v2/TextDisplay.js';
+import { normalizeArray, type RestOrArray } from '../../util/normalizeArray.js';
+import { resolveBuilder } from '../../util/resolveBuilder.js';
+import { validate } from '../../util/validation.js';
+import { modalPredicate } from './Assertions.js';
+
+export interface ModalBuilderData extends Partial<Omit<APIModalInteractionResponseCallbackData, 'components'>> {
+	components: (ActionRowBuilder | AnyModalComponentBuilder)[];
+}
+
+/**
+ * A builder that creates API-compatible JSON data for modals.
+ */
+export class ModalBuilder implements JSONEncodable<APIModalInteractionResponseCallbackData> {
+	/**
+	 * The API data associated with this modal.
+	 */
+	private readonly data: ModalBuilderData;
+
+	/**
+	 * The components within this modal.
+	 */
+	public get components(): readonly (ActionRowBuilder | AnyModalComponentBuilder)[] {
+		return this.data.components;
+	}
+
+	/**
+	 * Creates a new modal.
+	 *
+	 * @param data - The API data to create this modal with
+	 */
+	public constructor(data: Partial<APIModalInteractionResponseCallbackData> = {}) {
+		const { components = [], ...rest } = data;
+
+		this.data = {
+			...structuredClone(rest),
+			components: components.map((component) => createComponentBuilder(component)),
+		};
+	}
+
+	/**
+	 * Sets the title of this modal.
+	 *
+	 * @param title - The title to use
+	 */
+	public setTitle(title: string) {
+		this.data.title = title;
+		return this;
+	}
+
+	/**
+	 * Sets the custom id of this modal.
+	 *
+	 * @param customId - The custom id to use
+	 */
+	public setCustomId(customId: string) {
+		this.data.custom_id = customId;
+		return this;
+	}
+
+	/**
+	 * Adds label components to this modal.
+	 *
+	 * @param components - The components to add
+	 */
+	public addLabelComponents(
+		...components: RestOrArray<APILabelComponent | LabelBuilder | ((builder: LabelBuilder) => LabelBuilder)>
+	) {
+		const normalized = normalizeArray(components);
+		const resolved = normalized.map((label) => resolveBuilder(label, LabelBuilder));
+
+		this.data.components.push(...resolved);
+
+		return this;
+	}
+
+	/**
+	 * Adds text display components to this modal.
+	 *
+	 * @param components - The components to add
+	 */
+	public addTextDisplayComponents(
+		...components: RestOrArray<
+			APITextDisplayComponent | TextDisplayBuilder | ((builder: TextDisplayBuilder) => TextDisplayBuilder)
+		>
+	) {
+		const normalized = normalizeArray(components);
+		const resolved = normalized.map((row) => resolveBuilder(row, TextDisplayBuilder));
+
+		this.data.components.push(...resolved);
+
+		return this;
+	}
+
+	/**
+	 * Removes, replaces, or inserts components for this modal.
+	 *
+	 * @remarks
+	 * This method behaves similarly
+	 * to {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array/splice | Array.prototype.splice()}.
+	 * The maximum amount of components that can be added is 5.
+	 *
+	 * It's useful for modifying and adjusting order of the already-existing components of a modal.
+	 * @example
+	 * Remove the first component:
+	 * ```ts
+	 * modal.spliceComponents(0, 1);
+	 * ```
+	 * @example
+	 * Remove the first n components:
+	 * ```ts
+	 * const n = 4;
+	 * modal.spliceComponents(0, n);
+	 * ```
+	 * @example
+	 * Remove the last component:
+	 * ```ts
+	 * modal.spliceComponents(-1, 1);
+	 * ```
+	 * @param index - The index to start at
+	 * @param deleteCount - The number of components to remove
+	 * @param components - The replacing components
+	 */
+	public spliceComponents(index: number, deleteCount: number, ...components: AnyModalComponentBuilder[]): this {
+		this.data.components.splice(index, deleteCount, ...components);
+		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): APIModalInteractionResponseCallbackData {
+		const { components, ...rest } = this.data;
+
+		const data = {
+			...structuredClone(rest),
+			components: components.map((component) => component.toJSON(validationOverride)),
+		};
+
+		validate(modalPredicate, data, validationOverride);
+
+		return data as APIModalInteractionResponseCallbackData;
+	}
+}

package/src/messages/AllowedMentions.ts

@@ -0,0 +1,193 @@
+import type { JSONEncodable } from '@ovencord/util';
+import type { AllowedMentionsTypes, APIAllowedMentions, Snowflake } from 'discord-api-types/v10';
+import { normalizeArray, type RestOrArray } from '../util/normalizeArray.js';
+import { validate } from '../util/validation.js';
+import { allowedMentionPredicate } from './Assertions.js';
+
+/**
+ * A builder that creates API-compatible JSON data for allowed mentions.
+ */
+export class AllowedMentionsBuilder implements JSONEncodable<APIAllowedMentions> {
+	/**
+	 * The API data associated with these allowed mentions.
+	 */
+	private readonly data: Partial<APIAllowedMentions>;
+
+	/**
+	 * Creates a new allowed mentions builder.
+	 *
+	 * @param data - The API data to create this allowed mentions with
+	 */
+	public constructor(data: Partial<APIAllowedMentions> = {}) {
+		this.data = structuredClone(data);
+	}
+
+	/**
+	 * Sets the types of mentions to parse from the content.
+	 *
+	 * @param parse - The types of mentions to parse from the content
+	 */
+	public setParse(...parse: RestOrArray<AllowedMentionsTypes>): this {
+		this.data.parse = normalizeArray(parse);
+		return this;
+	}
+
+	/**
+	 * Clears the parse mention types.
+	 */
+	public clearParse(): this {
+		this.data.parse = undefined;
+		return this;
+	}
+
+	/**
+	 * Sets the roles to mention.
+	 *
+	 * @param roles - The roles to mention
+	 */
+	public setRoles(...roles: RestOrArray<Snowflake>): this {
+		this.data.roles = normalizeArray(roles);
+		return this;
+	}
+
+	/**
+	 * Adds roles to mention.
+	 *
+	 * @param roles - The roles to mention
+	 */
+	public addRoles(...roles: RestOrArray<Snowflake>): this {
+		this.data.roles ??= [];
+		this.data.roles.push(...normalizeArray(roles));
+
+		return this;
+	}
+
+	/**
+	 * Removes, replaces, or inserts roles.
+	 *
+	 * @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 roles.
+	 * @example
+	 * Remove the first role:
+	 * ```ts
+	 * allowedMentions.spliceRoles(0, 1);
+	 * ```
+	 * @example
+	 * Remove the first n roles:
+	 * ```ts
+	 * const n = 4;
+	 * allowedMentions.spliceRoles(0, n);
+	 * ```
+	 * @example
+	 * Remove the last role:
+	 * ```ts
+	 * allowedMentions.spliceRoles(-1, 1);
+	 * ```
+	 * @param index - The index to start at
+	 * @param deleteCount - The number of roles to remove
+	 * @param roles - The replacing role ids
+	 */
+	public spliceRoles(index: number, deleteCount: number, ...roles: RestOrArray<Snowflake>): this {
+		this.data.roles ??= [];
+		this.data.roles.splice(index, deleteCount, ...normalizeArray(roles));
+		return this;
+	}
+
+	/**
+	 * Clears the roles to mention.
+	 */
+	public clearRoles(): this {
+		this.data.roles = undefined;
+		return this;
+	}
+
+	/**
+	 * Sets the users to mention.
+	 *
+	 * @param users - The users to mention
+	 */
+	public setUsers(...users: RestOrArray<Snowflake>): this {
+		this.data.users = normalizeArray(users);
+		return this;
+	}
+
+	/**
+	 * Adds users to mention.
+	 *
+	 * @param users - The users to mention
+	 */
+	public addUsers(...users: RestOrArray<Snowflake>): this {
+		this.data.users ??= [];
+		this.data.users.push(...normalizeArray(users));
+		return this;
+	}
+
+	/**
+	 * Removes, replaces, or inserts users.
+	 *
+	 * @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 users.
+	 * @example
+	 * Remove the first user:
+	 * ```ts
+	 * allowedMentions.spliceUsers(0, 1);
+	 * ```
+	 * @example
+	 * Remove the first n users:
+	 * ```ts
+	 * const n = 4;
+	 * allowedMentions.spliceUsers(0, n);
+	 * ```
+	 * @example
+	 * Remove the last user:
+	 * ```ts
+	 * allowedMentions.spliceUsers(-1, 1);
+	 * ```
+	 * @param index - The index to start at
+	 * @param deleteCount - The number of users to remove
+	 * @param users - The replacing user ids
+	 */
+	public spliceUsers(index: number, deleteCount: number, ...users: RestOrArray<Snowflake>): this {
+		this.data.users ??= [];
+		this.data.users.splice(index, deleteCount, ...normalizeArray(users));
+		return this;
+	}
+
+	/**
+	 * Clears the users to mention.
+	 */
+	public clearUsers(): this {
+		this.data.users = undefined;
+		return this;
+	}
+
+	/**
+	 * For replies, sets whether to mention the author of the message being replied to.
+	 *
+	 * @param repliedUser - Whether to mention the author of the message being replied to
+	 */
+	public setRepliedUser(repliedUser = true): this {
+		this.data.replied_user = repliedUser;
+		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): APIAllowedMentions {
+		const clone = structuredClone(this.data);
+		validate(allowedMentionPredicate, clone, validationOverride);
+
+		return clone as APIAllowedMentions;
+	}
+}

package/src/messages/Assertions.ts

@@ -0,0 +1,148 @@
+import { Buffer } from 'node:buffer';
+import { AllowedMentionsTypes, ComponentType, MessageFlags, MessageReferenceType } from 'discord-api-types/v10';
+import { z } from 'zod';
+import { snowflakePredicate } from '../Assertions.js';
+import { embedPredicate } from './embed/Assertions.js';
+import { pollPredicate } from './poll/Assertions.js';
+
+const fileKeyRegex = /^files\[(?<placeholder>\d+?)]$/;
+
+export const rawFilePredicate = z.object({
+	data: z.union([z.instanceof(Buffer), z.instanceof(Uint8Array), z.string()]),
+	name: z.string().min(1),
+	contentType: z.string().optional(),
+	key: z.string().regex(fileKeyRegex).optional(),
+});
+
+export const attachmentPredicate = z.object({
+	// As a string it only makes sense for edits when we do have an attachment snowflake
+	id: z.union([snowflakePredicate, z.number()]),
+	description: z.string().max(1_024).optional(),
+	duration_secs: z
+		.number()
+		.max(2 ** 31 - 1)
+		.optional(),
+	filename: z.string().max(1_024).optional(),
+	title: z.string().max(1_024).optional(),
+	waveform: z.string().max(400).optional(),
+});
+
+export const allowedMentionPredicate = z
+	.object({
+		parse: z.nativeEnum(AllowedMentionsTypes).array().optional(),
+		roles: z.string().array().max(100).optional(),
+		users: z.string().array().max(100).optional(),
+		replied_user: z.boolean().optional(),
+	})
+	.refine(
+		(data) =>
+			!(
+				(data.parse?.includes(AllowedMentionsTypes.User) && data.users?.length) ||
+				(data.parse?.includes(AllowedMentionsTypes.Role) && data.roles?.length)
+			),
+		{
+			message:
+				'Cannot specify both parse: ["users"] and non-empty users array, or parse: ["roles"] and non-empty roles array. These are mutually exclusive',
+		},
+	);
+
+export const messageReferencePredicate = z.object({
+	channel_id: z.string().optional(),
+	fail_if_not_exists: z.boolean().optional(),
+	guild_id: z.string().optional(),
+	message_id: z.string(),
+	type: z.nativeEnum(MessageReferenceType).optional(),
+});
+
+const baseMessagePredicate = z.object({
+	nonce: z.union([z.string().max(25), z.number()]).optional(),
+	tts: z.boolean().optional(),
+	allowed_mentions: allowedMentionPredicate.optional(),
+	message_reference: messageReferencePredicate.optional(),
+	attachments: attachmentPredicate.array().max(10).optional(),
+	enforce_nonce: z.boolean().optional(),
+});
+
+const basicActionRowPredicate = z.object({
+	type: z.literal(ComponentType.ActionRow),
+	components: z
+		.object({
+			type: z.union([
+				z.literal(ComponentType.Button),
+				z.literal(ComponentType.ChannelSelect),
+				z.literal(ComponentType.MentionableSelect),
+				z.literal(ComponentType.RoleSelect),
+				z.literal(ComponentType.StringSelect),
+				z.literal(ComponentType.UserSelect),
+			]),
+		})
+		.array(),
+});
+
+const messageNoComponentsV2Predicate = baseMessagePredicate
+	.extend({
+		content: z.string().max(2_000).optional(),
+		embeds: embedPredicate.array().max(10).optional(),
+		sticker_ids: z.array(z.string()).max(3).optional(),
+		poll: pollPredicate.optional(),
+		components: basicActionRowPredicate.array().max(5).optional(),
+		flags: z
+			.number()
+			.int()
+			.optional()
+			.refine((flags) => !flags || (flags & MessageFlags.IsComponentsV2) === 0, {
+				message: 'Cannot set content, embeds, stickers, or poll with IsComponentsV2 flag set',
+			}),
+	})
+	.refine(
+		(data) =>
+			data.content !== undefined ||
+			(data.embeds !== undefined && data.embeds.length > 0) ||
+			data.poll !== undefined ||
+			(data.attachments !== undefined && data.attachments.length > 0) ||
+			(data.components !== undefined && data.components.length > 0) ||
+			(data.sticker_ids !== undefined && data.sticker_ids.length > 0),
+		{ message: 'Messages must have content, embeds, a poll, attachments, components or stickers' },
+	);
+
+const allTopLevelComponentsPredicate = z
+	.union([
+		basicActionRowPredicate,
+		z.object({
+			type: z.union([
+				// Components v2
+				z.literal(ComponentType.Container),
+				z.literal(ComponentType.File),
+				z.literal(ComponentType.MediaGallery),
+				z.literal(ComponentType.Section),
+				z.literal(ComponentType.Separator),
+				z.literal(ComponentType.TextDisplay),
+				z.literal(ComponentType.Thumbnail),
+			]),
+		}),
+	])
+	.array()
+	.min(1)
+	.max(10);
+
+const messageComponentsV2Predicate = baseMessagePredicate.extend({
+	components: allTopLevelComponentsPredicate,
+	flags: z.number().int().refine((flags) => (flags & MessageFlags.IsComponentsV2) === MessageFlags.IsComponentsV2, {
+		message: 'Must set IsComponentsV2 flag to use Components V2',
+	}),
+	// These fields cannot be set
+	content: z.string().length(0).nullish(),
+	embeds: z.array(z.never()).nullish(),
+	sticker_ids: z.array(z.never()).nullish(),
+	poll: z.null().optional(),
+});
+
+export const messagePredicate = z.union([messageNoComponentsV2Predicate, messageComponentsV2Predicate]);
+
+// This validator does not assert file.key <-> attachment.id coherence. This is fine, because the builders
+// should effectively guarantee that.
+export const fileBodyMessagePredicate = z.object({
+	body: messagePredicate,
+	// No min length to support message edits
+	files: rawFilePredicate.array().max(10),
+});