@ovencord/builders 1.11.1

package/src/messages/embed/EmbedFooter.ts

@@ -0,0 +1,65 @@
+import type { JSONEncodable } from '@ovencord/util';
+import type { APIEmbedFooter } from 'discord-api-types/v10';
+import { validate } from '../../util/validation.js';
+import { embedFooterPredicate } from './Assertions.js';
+
+/**
+ * A builder that creates API-compatible JSON data for the embed footer.
+ */
+export class EmbedFooterBuilder implements JSONEncodable<APIEmbedFooter> {
+	/**
+	 * The API data associated with this embed footer.
+	 */
+	private readonly data: Partial<APIEmbedFooter>;
+
+	/**
+	 * Creates a new embed footer.
+	 *
+	 * @param data - The API data to create this embed footer with
+	 */
+	public constructor(data: Partial<APIEmbedFooter> = {}) {
+		this.data = structuredClone(data);
+	}
+
+	/**
+	 * Sets the text for this embed footer.
+	 *
+	 * @param text - The text to use
+	 */
+	public setText(text: string): this {
+		this.data.text = text;
+		return this;
+	}
+
+	/**
+	 * Sets the url for this embed footer.
+	 *
+	 * @param url - The url to use
+	 */
+	public setIconURL(url: string): this {
+		this.data.icon_url = url;
+		return this;
+	}
+
+	/**
+	 * Clears the icon URL for this embed footer.
+	 */
+	public clearIconURL(): this {
+		this.data.icon_url = 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 toJSON(validationOverride?: boolean): APIEmbedFooter {
+		const clone = structuredClone(this.data);
+		validate(embedFooterPredicate, clone, validationOverride);
+
+		return clone as APIEmbedFooter;
+	}
+}

package/src/messages/poll/Assertions.ts

@@ -0,0 +1,20 @@
+import { PollLayoutType } from 'discord-api-types/v10';
+import { z } from 'zod';
+import { emojiPredicate } from '../../components/Assertions';
+
+export const pollQuestionPredicate = z.object({ text: z.string().min(1).max(300) });
+
+export const pollAnswerMediaPredicate = z.object({
+	text: z.string().min(1).max(55),
+	emoji: emojiPredicate.optional(),
+});
+
+export const pollAnswerPredicate = z.object({ poll_media: pollAnswerMediaPredicate });
+
+export const pollPredicate = z.object({
+	question: pollQuestionPredicate,
+	answers: z.array(pollAnswerPredicate).min(1).max(10),
+	duration: z.number().min(1).max(768).optional(),
+	allow_multiselect: z.boolean().optional(),
+	layout_type: z.nativeEnum(PollLayoutType).optional(),
+});

package/src/messages/poll/Poll.ts

@@ -0,0 +1,243 @@
+import type { JSONEncodable } from '@ovencord/util';
+import type { RESTAPIPoll, APIPollMedia, PollLayoutType, APIPollAnswer } 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 { pollPredicate } from './Assertions';
+import { PollAnswerBuilder } from './PollAnswer.js';
+import { PollQuestionBuilder } from './PollQuestion.js';
+
+export interface PollData extends Omit<RESTAPIPoll, 'answers' | 'question'> {
+	answers: PollAnswerBuilder[];
+	question: PollQuestionBuilder;
+}
+
+/**
+ * A builder that creates API-compatible JSON data for polls.
+ */
+export class PollBuilder implements JSONEncodable<RESTAPIPoll> {
+	/**
+	 * The API data associated with this poll.
+	 */
+	private readonly data: PollData;
+
+	/**
+	 * Gets the answers of this poll.
+	 */
+	public get answers(): readonly PollAnswerBuilder[] {
+		return this.data.answers;
+	}
+
+	/**
+	 * Creates a new poll.
+	 *
+	 * @param data - The API data to create this poll with
+	 */
+	public constructor(data: Partial<RESTAPIPoll> = {}) {
+		const { question, answers = [], ...rest } = data;
+
+		this.data = {
+			...structuredClone(rest),
+			question: new PollQuestionBuilder(question),
+			answers: answers.map((answer) => new PollAnswerBuilder(answer)),
+		};
+	}
+
+	/**
+	 * Appends answers to the poll.
+	 *
+	 * @remarks
+	 * This method accepts either an array of answers or a variable number of answer parameters.
+	 * The maximum amount of answers that can be added is 10.
+	 * @example
+	 * Using an array:
+	 * ```ts
+	 * const answers: APIPollMedia[] = ...;
+	 * const poll = new PollBuilder()
+	 * 	.addAnswers(answers);
+	 * ```
+	 * @example
+	 * Using rest parameters (variadic):
+	 * ```ts
+	 * const poll = new PollBuilder()
+	 * 	.addAnswers(
+	 * 		{ text: 'Answer 1' },
+	 * 		{ text: 'Answer 2' },
+	 * 	);
+	 * ```
+	 * @param answers - The answers to add
+	 */
+	public addAnswers(
+		...answers: RestOrArray<
+			Omit<APIPollAnswer, 'answer_id'> | PollAnswerBuilder | ((builder: PollAnswerBuilder) => PollAnswerBuilder)
+		>
+	): this {
+		const normalizedAnswers = normalizeArray(answers);
+		const resolved = normalizedAnswers.map((answer) => resolveBuilder(answer, PollAnswerBuilder));
+
+		this.data.answers.push(...resolved);
+		return this;
+	}
+
+	/**
+	 * Removes, replaces, or inserts answers for this poll.
+	 *
+	 * @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 answers that can be added is 10.
+	 *
+	 * It's useful for modifying and adjusting order of the already-existing answers of a poll.
+	 * @example
+	 * Remove the first answer:
+	 * ```ts
+	 * poll.spliceAnswers(0, 1);
+	 * ```
+	 * @example
+	 * Remove the first n answers:
+	 * ```ts
+	 * const n = 4;
+	 * poll.spliceAnswers(0, n);
+	 * ```
+	 * @example
+	 * Remove the last answer:
+	 * ```ts
+	 * poll.spliceAnswers(-1, 1);
+	 * ```
+	 * @param index - The index to start at
+	 * @param deleteCount - The number of answers to remove
+	 * @param answers - The replacing answer objects
+	 */
+	public spliceAnswers(
+		index: number,
+		deleteCount: number,
+		...answers: (
+			| Omit<APIPollAnswer, 'answer_id'>
+			| PollAnswerBuilder
+			| ((builder: PollAnswerBuilder) => PollAnswerBuilder)
+		)[]
+	): this {
+		const normalizedAnswers = normalizeArray(answers);
+		const resolved = normalizedAnswers.map((answer) => resolveBuilder(answer, PollAnswerBuilder));
+
+		this.data.answers.splice(index, deleteCount, ...resolved);
+		return this;
+	}
+
+	/**
+	 * Sets the answers for this poll.
+	 *
+	 * @remarks
+	 * This method is an alias for {@link PollBuilder.spliceAnswers}. More specifically,
+	 * it splices the entire array of answers, replacing them with the provided answers.
+	 *
+	 * You can set a maximum of 10 answers.
+	 * @param answers - The answers to set
+	 */
+	public setAnswers(
+		...answers: RestOrArray<
+			Omit<APIPollAnswer, 'answer_id'> | PollAnswerBuilder | ((builder: PollAnswerBuilder) => PollAnswerBuilder)
+		>
+	): this {
+		return this.spliceAnswers(0, this.data.answers.length, ...normalizeArray(answers));
+	}
+
+	/**
+	 * Sets the question for this poll.
+	 *
+	 * @param options - The data to use for this poll's question
+	 */
+	public setQuestion(
+		options:
+			| Omit<APIPollMedia, 'emoji'>
+			| PollQuestionBuilder
+			| ((builder: PollQuestionBuilder) => PollQuestionBuilder),
+	): this {
+		this.data.question = resolveBuilder(options, PollQuestionBuilder);
+		return this;
+	}
+
+	/**
+	 * Updates the question of this poll.
+	 *
+	 * @param updater - The function to update the question with
+	 */
+	public updateQuestion(updater: (builder: PollQuestionBuilder) => void): this {
+		updater(this.data.question);
+		return this;
+	}
+
+	/**
+	 * Sets the layout type for this poll.
+	 *
+	 * @remarks
+	 * This method is redundant while only one type of poll layout exists (`PollLayoutType.Default`)
+	 * with Discord using that as the layout type if none is specified.
+	 * @param type - The type of poll layout to use
+	 */
+	public setLayoutType(type: PollLayoutType): this {
+		this.data.layout_type = type;
+		return this;
+	}
+
+	/**
+	 * Clears the layout type for this poll.
+	 */
+	public clearLayoutType(): this {
+		this.data.layout_type = undefined;
+		return this;
+	}
+
+	/**
+	 * Sets whether multi-select is enabled for this poll.
+	 *
+	 * @param multiSelect - Whether to allow multi-select
+	 */
+	public setMultiSelect(multiSelect = true): this {
+		this.data.allow_multiselect = multiSelect;
+		return this;
+	}
+
+	/**
+	 * Sets how long this poll will be open for in hours.
+	 *
+	 * @remarks
+	 * Minimum duration is `1`, with maximum duration being `768` (32 days).
+	 * Default if none specified is `24` (one day).
+	 * @param duration - The amount of hours this poll will be open for
+	 */
+	public setDuration(duration: number): this {
+		this.data.duration = duration;
+		return this;
+	}
+
+	/**
+	 * Clears the duration for this poll.
+	 */
+	public clearDuration(): this {
+		this.data.duration = 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 toJSON(validationOverride?: boolean): RESTAPIPoll {
+		const { answers, question, ...rest } = this.data;
+
+		const data = {
+			...structuredClone(rest),
+			// Disable validation because the pollPredicate below will validate those as well
+			answers: answers.map((answer) => answer.toJSON(false)),
+			question: question.toJSON(false),
+		};
+
+		validate(pollPredicate, data, validationOverride);
+
+		return data;
+	}
+}

package/src/messages/poll/PollAnswer.ts

@@ -0,0 +1,77 @@
+import type { JSONEncodable } from '@ovencord/util';
+import type { APIPollAnswer, APIPollMedia } from 'discord-api-types/v10';
+import { resolveBuilder } from '../../util/resolveBuilder';
+import { validate } from '../../util/validation';
+import { pollAnswerPredicate } from './Assertions';
+import { PollAnswerMediaBuilder } from './PollAnswerMedia';
+
+export interface PollAnswerData extends Omit<APIPollAnswer, 'answer_id' | 'poll_media'> {
+	poll_media: PollAnswerMediaBuilder;
+}
+
+/**
+ * A builder that creates API-compatible JSON data for poll answers.
+ */
+export class PollAnswerBuilder implements JSONEncodable<Omit<APIPollAnswer, 'answer_id'>> {
+	/**
+	 * The API data associated with this poll answer.
+	 */
+	private readonly data: PollAnswerData;
+
+	/**
+	 * Creates a new poll answer.
+	 *
+	 * @param data - The API data to create this poll answer with
+	 */
+	public constructor(data: Partial<Omit<APIPollAnswer, 'answer_id'>> = {}) {
+		const { poll_media, ...rest } = data;
+
+		this.data = {
+			...structuredClone(rest),
+			poll_media: new PollAnswerMediaBuilder(poll_media),
+		};
+	}
+
+	/**
+	 * Sets the media for this poll answer.
+	 *
+	 * @param options - The data to use for this poll answer's media
+	 */
+	public setMedia(
+		options: APIPollMedia | PollAnswerMediaBuilder | ((builder: PollAnswerMediaBuilder) => PollAnswerMediaBuilder),
+	): this {
+		this.data.poll_media = resolveBuilder(options, PollAnswerMediaBuilder);
+		return this;
+	}
+
+	/**
+	 * Updates the media of this poll answer.
+	 *
+	 * @param updater - The function to update the media with
+	 */
+	public updateMedia(updater: (builder: PollAnswerMediaBuilder) => void): this {
+		updater(this.data.poll_media);
+		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): Omit<APIPollAnswer, 'answer_id'> {
+		const { poll_media, ...rest } = this.data;
+
+		const data = {
+			...structuredClone(rest),
+			// Disable validation because the pollAnswerPredicate below will validate this as well
+			poll_media: poll_media.toJSON(false),
+		};
+
+		validate(pollAnswerPredicate, data, validationOverride);
+
+		return data;
+	}
+}

package/src/messages/poll/PollAnswerMedia.ts

@@ -0,0 +1,38 @@
+import type { APIPartialEmoji, APIPollMedia } from 'discord-api-types/v10';
+import { validate } from '../../util/validation.js';
+import { pollAnswerMediaPredicate } from './Assertions.js';
+import { PollMediaBuilder } from './PollMedia.js';
+
+/**
+ * A builder that creates API-compatible JSON data for the media of a poll answer.
+ */
+export class PollAnswerMediaBuilder extends PollMediaBuilder {
+	/**
+	 * Sets the emoji for this poll answer media.
+	 *
+	 * @param emoji - The emoji to use
+	 */
+	public setEmoji(emoji: APIPartialEmoji): this {
+		this.data.emoji = emoji;
+		return this;
+	}
+
+	/**
+	 * Clears the emoji for this poll answer media.
+	 */
+	public clearEmoji(): this {
+		this.data.emoji = undefined;
+		return this;
+	}
+
+	/**
+	 * {@inheritDoc PollMediaBuilder.toJSON}
+	 */
+	public override toJSON(validationOverride?: boolean): APIPollMedia {
+		const clone = structuredClone(this.data);
+
+		validate(pollAnswerMediaPredicate, clone, validationOverride);
+
+		return clone;
+	}
+}

package/src/messages/poll/PollMedia.ts

@@ -0,0 +1,41 @@
+import type { APIPollMedia } from 'discord-api-types/v10';
+
+/**
+ * The base poll media builder that contains common symbols for poll media builders.
+ */
+export abstract class PollMediaBuilder {
+	/**
+	 * The API data associated with this poll media.
+	 *
+	 * @internal
+	 */
+	protected readonly data: Partial<APIPollMedia>;
+
+	/**
+	 * Creates new poll media.
+	 *
+	 * @param data - The API data to create this poll media with
+	 */
+	public constructor(data: Partial<APIPollMedia> = {}) {
+		this.data = structuredClone(data);
+	}
+
+	/**
+	 * Sets the text for this poll media.
+	 *
+	 * @param text - The text to use
+	 */
+	public setText(text: string): this {
+		this.data.text = text;
+		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): APIPollMedia;
+}

package/src/messages/poll/PollQuestion.ts

@@ -0,0 +1,20 @@
+import type { APIPollMedia } from 'discord-api-types/v10';
+import { validate } from '../../util/validation.js';
+import { pollQuestionPredicate } from './Assertions.js';
+import { PollMediaBuilder } from './PollMedia.js';
+
+/**
+ * A builder that creates API-compatible JSON data for a poll question.
+ */
+export class PollQuestionBuilder extends PollMediaBuilder {
+	/**
+	 * {@inheritDoc PollMediaBuilder.toJSON}
+	 */
+	public override toJSON(validationOverride?: boolean): Omit<APIPollMedia, 'emoji'> {
+		const clone = structuredClone(this.data);
+
+		validate(pollQuestionPredicate, clone, validationOverride);
+
+		return clone;
+	}
+}

package/src/util/ValidationError.ts

@@ -0,0 +1,21 @@
+import type { z } from 'zod';
+
+/**
+ * An error that is thrown when validation fails.
+ */
+export class ValidationError extends Error {
+	/**
+	 * The underlying cause of the validation error.
+	 */
+	public override readonly cause: z.ZodError;
+
+	/**
+	 * @internal
+	 */
+	public constructor(error: z.ZodError) {
+		super(error.message);
+
+		this.name = 'ValidationError';
+		this.cause = error;
+	}
+}

package/src/util/normalizeArray.ts

@@ -0,0 +1,19 @@
+/**
+ * Normalizes data that is a rest parameter or an array into an array with a depth of 1.
+ *
+ * @typeParam ItemType - The data that must satisfy {@link RestOrArray}.
+ * @param arr - The (possibly variadic) data to normalize
+ */
+export function normalizeArray<ItemType>(arr: RestOrArray<ItemType>): ItemType[] {
+	if (Array.isArray(arr[0])) return [...arr[0]];
+	return arr as ItemType[];
+}
+
+/**
+ * Represents data that may be an array or came from a rest parameter.
+ *
+ * @remarks
+ * This type is used throughout builders to ensure both an array and variadic arguments
+ * may be used. It is normalized with {@link normalizeArray}.
+ */
+export type RestOrArray<Type> = Type[] | [Type[]];

package/src/util/resolveBuilder.ts

@@ -0,0 +1,40 @@
+import type { JSONEncodable } from '@ovencord/util';
+
+/**
+ * @privateRemarks
+ * This is a type-guard util, because if you were to in-line `builder instanceof Constructor` in the `resolveBuilder`
+ * function, TS doesn't narrow out the type `Builder`, causing a type error on the last return statement.
+ * @internal
+ */
+function isBuilder<Builder extends JSONEncodable<any>>(
+	builder: unknown,
+	Constructor: new () => Builder,
+): builder is Builder {
+	return builder instanceof Constructor;
+}
+
+/**
+ * "Resolves" a builder from the 3 ways it can be input:
+ * 1. A clean instance
+ * 2. A data object that can be used to construct the builder
+ * 3. A function that takes a builder and returns a builder e.g. `builder => builder.setFoo('bar')`
+ *
+ * @typeParam Builder - The builder type
+ * @typeParam BuilderData - The data object that can be used to construct the builder
+ * @param builder - The user input, as described in the function description
+ * @param Constructor - The constructor of the builder
+ */
+export function resolveBuilder<Builder extends JSONEncodable<any>, BuilderData extends Record<PropertyKey, any>>(
+	builder: Builder | BuilderData | ((builder: Builder) => Builder),
+	Constructor: new (data?: BuilderData) => Builder,
+): Builder {
+	if (isBuilder(builder, Constructor)) {
+		return builder;
+	}
+
+	if (typeof builder === 'function') {
+		return builder(new Constructor());
+	}
+
+	return new Constructor(builder);
+}

package/src/util/validation.ts

@@ -0,0 +1,58 @@
+import type { z } from 'zod';
+import { ValidationError } from './ValidationError.js';
+
+let validationEnabled = true;
+
+/**
+ * Enables validators.
+ *
+ * @returns Whether validation is occurring.
+ */
+export function enableValidators() {
+	return (validationEnabled = true);
+}
+
+/**
+ * Disables validators.
+ *
+ * @returns Whether validation is occurring.
+ */
+export function disableValidators() {
+	return (validationEnabled = false);
+}
+
+/**
+ * Checks whether validation is occurring.
+ */
+export function isValidationEnabled() {
+	return validationEnabled;
+}
+
+/**
+ * Parses a value with a given validator, accounting for whether validation is enabled.
+ *
+ * @param validator - The zod validator to use
+ * @param value - The value to parse
+ * @param validationOverride - Force validation to run/not run regardless of your global preference
+ * @returns The result from parsing
+ * @throws {@link ValidationError}
+ * Throws if the value does not pass validation, if enabled.
+ * @internal
+ */
+export function validate<Validator extends z.ZodType>(
+	validator: Validator,
+	value: unknown,
+	validationOverride?: boolean,
+): z.output<Validator> {
+	if (validationOverride === false || (validationOverride === undefined && !isValidationEnabled())) {
+		return value as z.output<Validator>;
+	}
+
+	const result = validator.safeParse(value);
+
+	if (!result.success) {
+		throw new ValidationError(result.error);
+	}
+
+	return result.data;
+}