@lunibee/builders 0.1.8 → 0.2.0

package/README.md

@@ -55,4 +55,8 @@ 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.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.0",
   "type": "module",
   "module": "./src/index.ts",
   "types": "./src/index.ts",

package/src/components.ts

@@ -35,6 +35,8 @@ export interface APIButtonComponent {
     label?: string;
     emoji?: APIComponentEmoji;
     url?: string;
+    /** SKU for premium (style 6) buttons. */
+    sku_id?: string;
     disabled?: boolean;
 }
 export interface APISelectOption {
@@ -175,10 +177,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 +250,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 +266,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 +306,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 +327,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 +405,7 @@ export class EntitySelectBuilder {
         return this;
     }
     public toJSON(): APIEntitySelectComponent {
+        assertSelect(this.#data);
         return structuredClone(this.#data);
     }
 }
@@ -372,6 +436,10 @@ export class ModalBuilder {
         return this;
     }
     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 } : {}),
@@ -424,7 +492,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 +745,15 @@ 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.");
+}