@lunibee/builders 0.1.8 → 0.2.1

package/README.md

@@ -55,4 +55,15 @@ console.log(embed.toJSON(), buttons.toJSON(), menu.toJSON(), ping.toJSON());
 
 Every builder validates Discord's limits as you set values and serialises with `toJSON()`.
 
+## What's new in 0.2.1
+
+- `ModalBuilder.addTextInputs(...inputs)` wraps each text input in its own row.
+- `componentsV2Message(components, options?)` builds a Components V2 message with the required flag.
+- `EmbedBuilder` setters (`setTitle`, `setDescription`, `setURL`, `setThumbnail`, `setImage`) clear the field with `null`.
+- `TextInputStyle` and `ComponentType` are usable as types; `ModalBuilder.toJSON()` is typed with a required `custom_id` and `title`.
+
+## What's new in 0.2.0
+
+`toJSON()` validates whole components (required fields, value bounds, action-row rules, button field exclusivity); `ButtonBuilder.setSKUId()` for premium buttons.
+
 Docs: https://lunibee.js.org/core-concepts/builders/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunibee/builders",
-  "version": "0.1.8",
+  "version": "0.2.1",
   "type": "module",
   "module": "./src/index.ts",
   "types": "./src/index.ts",

package/src/components.ts

@@ -23,6 +23,11 @@ export const ComponentType = {
     Container: 17,
 } as const;
 export const TextInputStyle = { Short: 1, Paragraph: 2 } as const;
+/** One {@link TextInputStyle} value, usable as a type. */
+export type TextInputStyle =
+    (typeof TextInputStyle)[keyof typeof TextInputStyle];
+/** One {@link ComponentType} value, usable as a type. */
+export type ComponentType = (typeof ComponentType)[keyof typeof ComponentType];
 export interface APIComponentEmoji {
     id?: string | null;
     name?: string | null;
@@ -35,6 +40,8 @@ export interface APIButtonComponent {
     label?: string;
     emoji?: APIComponentEmoji;
     url?: string;
+    /** SKU for premium (style 6) buttons. */
+    sku_id?: string;
     disabled?: boolean;
 }
 export interface APISelectOption {
@@ -81,8 +88,8 @@ export interface APITextInputComponent {
 }
 export interface APIModalComponent {
     type: 9;
-    custom_id?: string;
-    title?: string;
+    custom_id: string;
+    title: string;
     components: APIActionRowComponent[];
 }
 export type APIActionRowChild =
@@ -175,10 +182,20 @@ export class ActionRowBuilder<
         return this;
     }
     public toJSON(): APIActionRowComponent {
-        return {
-            type: ComponentType.ActionRow,
-            components: this.#components.map((component) => component.toJSON()),
-        };
+        const components = this.#components.map((component) =>
+            component.toJSON(),
+        );
+        if (components.length === 0)
+            throw new RangeError("An action row needs at least one component.");
+        const types = components.map((component) => component.type);
+        if (
+            types.some((type) => type !== ComponentType.Button) &&
+            components.length > 1
+        )
+            throw new RangeError(
+                "A select menu or text input must be alone in its action row.",
+            );
+        return { type: ComponentType.ActionRow, components };
     }
 }
 export class StringSelectBuilder {
@@ -238,6 +255,14 @@ export class StringSelectBuilder {
         return this;
     }
     public toJSON(): APIStringSelectComponent {
+        assertSelect(this.#data);
+        const count = this.#data.options?.length ?? 0;
+        if (count === 0)
+            throw new RangeError("A string select needs at least one option.");
+        if ((this.#data.max_values ?? 1) > count)
+            throw new RangeError(
+                "max_values cannot exceed the number of options.",
+            );
         return structuredClone(this.#data);
     }
 }
@@ -246,9 +271,22 @@ export class ButtonBuilder {
         type: ComponentType.Button,
         style: ButtonStyle.Secondary,
     };
+    /** Sets the style and drops fields that style cannot carry. */
     public setStyle(style: APIButtonComponent["style"]): this {
-        this.#data.style = style;
-        if (style === ButtonStyle.Link) delete this.#data.custom_id;
+        const data = this.#data;
+        data.style = style;
+        if (style === ButtonStyle.Link) {
+            delete data.custom_id;
+            delete data.sku_id;
+        } else if (style === ButtonStyle.Premium) {
+            delete data.custom_id;
+            delete data.url;
+            delete data.label;
+            delete data.emoji;
+        } else {
+            delete data.url;
+            delete data.sku_id;
+        }
         return this;
     }
     public setCustomId(value: string): this {
@@ -273,11 +311,17 @@ export class ButtonBuilder {
                 cause: error,
             });
         }
-        this.#data.style = ButtonStyle.Link;
-        delete this.#data.custom_id;
+        this.setStyle(ButtonStyle.Link);
         this.#data.url = url.toString();
         return this;
     }
+    /** Makes this a premium (purchase) button for a SKU. Premium buttons carry no label, emoji, custom ID or URL. */
+    public setSKUId(skuId: string): this {
+        validateText(skuId, 20, "Button SKU ID");
+        this.setStyle(ButtonStyle.Premium);
+        this.#data.sku_id = skuId;
+        return this;
+    }
     public setEmoji(emoji: APIComponentEmoji | string): this {
         this.#data.emoji =
             typeof emoji === "string" ? { name: emoji } : { ...emoji };
@@ -288,7 +332,31 @@ export class ButtonBuilder {
         return this;
     }
     public toJSON(): APIButtonComponent {
-        return structuredClone(this.#data);
+        const data = this.#data;
+        if (data.style === ButtonStyle.Link) {
+            if (!data.url) throw new TypeError("Link buttons require a URL.");
+            if (data.custom_id || data.sku_id)
+                throw new TypeError(
+                    "Link buttons cannot have a custom ID or SKU ID.",
+                );
+        } else if (data.style === ButtonStyle.Premium) {
+            if (!data.sku_id)
+                throw new TypeError("Premium buttons require a SKU ID.");
+            if (data.custom_id || data.url || data.label || data.emoji)
+                throw new TypeError(
+                    "Premium buttons cannot have a custom ID, URL, label or emoji.",
+                );
+        } else {
+            if (!data.custom_id)
+                throw new TypeError("Non-link buttons require a custom ID.");
+            if (data.url || data.sku_id)
+                throw new TypeError(
+                    "Only link buttons have a URL and only premium buttons have a SKU ID.",
+                );
+        }
+        if (data.style !== ButtonStyle.Premium && !data.label && !data.emoji)
+            throw new TypeError("Buttons require a label or an emoji.");
+        return structuredClone(data);
     }
 }
 export class EntitySelectBuilder {
@@ -342,6 +410,7 @@ export class EntitySelectBuilder {
         return this;
     }
     public toJSON(): APIEntitySelectComponent {
+        assertSelect(this.#data);
         return structuredClone(this.#data);
     }
 }
@@ -371,11 +440,23 @@ export class ModalBuilder {
         this.#components.push(...components);
         return this;
     }
+    /** Adds text inputs, each in its own action row (Discord's modal layout). @param inputs Text inputs, at most 5 per modal. */
+    public addTextInputs(...inputs: TextInputBuilder[]): this {
+        return this.addComponents(
+            ...inputs.map((input) =>
+                new ActionRowBuilder<TextInputBuilder>().addComponents(input),
+            ),
+        );
+    }
     public toJSON(): APIModalComponent {
+        if (!this.#custom_id || !this.#title)
+            throw new TypeError("Modals require a custom ID and a title.");
+        if (this.#components.length === 0)
+            throw new RangeError("Modals require at least one component.");
         return {
             type: 9,
-            ...(this.#custom_id ? { custom_id: this.#custom_id } : {}),
-            ...(this.#title ? { title: this.#title } : {}),
+            custom_id: this.#custom_id,
+            title: this.#title,
             components: this.#components.map((component) => component.toJSON()),
         };
     }
@@ -424,7 +505,16 @@ export class TextInputBuilder {
         return this;
     }
     public toJSON(): APITextInputComponent {
-        return structuredClone(this.#data);
+        const data = this.#data;
+        if (!data.custom_id)
+            throw new TypeError("Text inputs require a custom ID.");
+        if (
+            data.min_length !== undefined &&
+            data.max_length !== undefined &&
+            data.min_length > data.max_length
+        )
+            throw new RangeError("min_length cannot exceed max_length.");
+        return structuredClone(data);
     }
 }
 
@@ -668,3 +758,43 @@ export class ChannelSelectMenuBuilder extends EntitySelectBuilder {
         super(ComponentType.ChannelSelect);
     }
 }
+
+/** Checks the fields every select menu needs. */
+function assertSelect(data: {
+    custom_id?: string;
+    min_values?: number;
+    max_values?: number;
+}): void {
+    if (!data.custom_id)
+        throw new TypeError("Select menus require a custom ID.");
+    if ((data.min_values ?? 1) > (data.max_values ?? 1))
+        throw new RangeError("min_values cannot exceed max_values.");
+}
+
+/** Discord's flag for a message laid out with Components V2 (containers, text displays...). */
+const IS_COMPONENTS_V2 = 1 << 15;
+
+/**
+ * A message payload laid out with Components V2: the components, and the flag
+ * Discord requires for them. A V2 message cannot also carry `content` or `embeds`.
+ * @param components Top-level components (containers, sections, text displays, action rows...).
+ * @param options Extra message fields, such as `allowed_mentions` or `ephemeral`; `flags` are combined.
+ * @example channel.send(componentsV2Message(new ContainerBuilder().addComponents(new TextDisplayBuilder().setContent("Hi"))))
+ */
+export function componentsV2Message<
+    T extends Record<string, unknown> = Record<string, never>,
+>(
+    components: { toJSON(): APIComponent } | Array<{ toJSON(): APIComponent }>,
+    options?: T & { flags?: number },
+): { components: APIComponent[]; flags: number } & T {
+    const list = Array.isArray(components) ? components : [components];
+    if (!list.length)
+        throw new TypeError(
+            "A Components V2 message needs at least one component.",
+        );
+    return {
+        ...(options ?? ({} as T)),
+        components: list.map((component) => component.toJSON()),
+        flags: (options?.flags ?? 0) | IS_COMPONENTS_V2,
+    };
+}

package/src/embed.ts

@@ -32,22 +32,26 @@ export interface APIEmbed {
 /** Builds compile-time-safe rich embed payloads for Discord API requests. */
 export class EmbedBuilder {
     readonly #data: APIEmbed = {};
-    /** Sets the embed title. @param value Title text. @returns This builder. @throws {RangeError} If title exceeds Discord's limit. */ public setTitle(
-        value: string,
+    /** Sets the embed title. @param value Title text, or null to clear. @returns This builder. @throws {RangeError} If title exceeds Discord's limit. */ public setTitle(
+        value: string | null,
     ): this {
-        this.#data.title = validate(value, 256, "Embed title");
+        if (value === null) delete this.#data.title;
+        else this.#data.title = validate(value, 256, "Embed title");
         return this;
     }
-    /** Sets the embed description. @param value Description text. @returns This builder. @throws {RangeError} If description exceeds Discord's limit. */ public setDescription(
-        value: string,
+    /** Sets the embed description. @param value Description text, or null to clear. @returns This builder. @throws {RangeError} If description exceeds Discord's limit. */ public setDescription(
+        value: string | null,
     ): this {
-        this.#data.description = validate(value, 4096, "Embed description");
+        if (value === null) delete this.#data.description;
+        else
+            this.#data.description = validate(value, 4096, "Embed description");
         return this;
     }
-    /** Sets the embed URL. @param value Absolute URL. @returns This builder. @throws {TypeError} If URL is invalid. */ public setURL(
-        value: string,
+    /** Sets the embed URL. @param value Absolute URL, or null to clear. @returns This builder. @throws {TypeError} If URL is invalid. */ public setURL(
+        value: string | null,
     ): this {
-        this.#data.url = url(value, "Embed URL");
+        if (value === null) delete this.#data.url;
+        else this.#data.url = url(value, "Embed URL");
         return this;
     }
     /** Sets the embed color. @param value RGB integer. @returns This builder. @throws {RangeError} If color is outside 24-bit RGB range. */ public setColor(
@@ -92,16 +96,24 @@ export class EmbedBuilder {
         };
         return this;
     }
-    /** Sets the thumbnail URL. @param value Thumbnail URL or payload. @returns This builder. @throws {TypeError} If URL is invalid. */ public setThumbnail(
-        value: { url: string } | string,
+    /** Sets the thumbnail URL. @param value Thumbnail URL or payload, or null to clear. @returns This builder. @throws {TypeError} If URL is invalid. */ public setThumbnail(
+        value: { url: string } | string | null,
     ): this {
+        if (value === null) {
+            delete this.#data.thumbnail;
+            return this;
+        }
         const valueURL = typeof value === "string" ? value : value.url;
         this.#data.thumbnail = { url: url(valueURL, "Thumbnail URL") };
         return this;
     }
-    /** Sets the image URL. @param value Image URL or payload. @returns This builder. @throws {TypeError} If URL is invalid. */ public setImage(
-        value: { url: string } | string,
+    /** Sets the image URL. @param value Image URL or payload, or null to clear. @returns This builder. @throws {TypeError} If URL is invalid. */ public setImage(
+        value: { url: string } | string | null,
     ): this {
+        if (value === null) {
+            delete this.#data.image;
+            return this;
+        }
         const valueURL = typeof value === "string" ? value : value.url;
         this.#data.image = { url: url(valueURL, "Image URL") };
         return this;

package/src/index.ts

@@ -23,6 +23,7 @@ export {
     SeparatorBuilder,
     ThumbnailBuilder,
     ContentInventoryEntryBuilder,
+    componentsV2Message,
 } from "./components.js";
 export {
     SlashCommandBuilder,