@lunibee/builders 0.3.1 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunibee/builders",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "type": "module",
   "module": "./src/index.ts",
   "types": "./src/index.ts",
@@ -8,6 +8,6 @@
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@lunibee/types": "^0.3.1"
+    "@lunibee/types": "^0.3.2"
   }
 }

package/src/attachment.ts

@@ -1,6 +1,7 @@
 import { readFile, realpath } from "node:fs/promises";
 import { basename, isAbsolute, relative, resolve } from "node:path";
 
+/** Options for `CreateAttachment`: file name, alt-text description, the contents or a file path, and an optional root folder the path must stay inside. */
 export interface AttachmentData {
     name: string;
     description?: string;
@@ -84,12 +85,20 @@ export class CreateAttachment {
 
 /** Resolves `file` against `root`, refusing anything outside it (after following symlinks). */
 async function insideRoot(root: string, file: string): Promise<string> {
-    const base = await realpath(root);
+    const base = await realpath(root).catch(() => {
+        throw new Error("Attachment root folder was not found.");
+    });
     const target = await realpath(resolve(base, file)).catch(() => {
         throw new Error("Attachment file was not found inside its root.");
     });
     const rel = relative(base, target);
-    if (rel === "" || rel.startsWith("..") || isAbsolute(rel))
+    if (
+        rel === "" ||
+        rel === ".." ||
+        rel.startsWith("../") ||
+        rel.startsWith("..\\") ||
+        isAbsolute(rel)
+    )
         throw new Error("Attachment file is outside its root folder.");
     return target;
 }

package/src/clone.ts

@@ -0,0 +1,27 @@
+/**
+ * A deep copy of builder data, for `toJSON()`.
+ *
+ * Builder payloads are plain JSON: objects, arrays and primitives. Copying
+ * those directly is several times faster than `structuredClone` on the small
+ * payloads builders hold. Anything else (a Date, a Map, a class instance) and
+ * anything nested deeper than 64 levels (a cycle) goes to `structuredClone`,
+ * so the result is what `structuredClone` would give.
+ */
+export function cloneData<T>(value: T, depth = 0): T {
+    if (value === null || typeof value !== "object") return value;
+    if (depth > 64) return structuredClone(value);
+    if (Array.isArray(value)) {
+        const out = new Array(value.length);
+        for (let i = 0; i < value.length; i++)
+            out[i] = cloneData(value[i], depth + 1);
+        return out as T;
+    }
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null)
+        return structuredClone(value);
+    const from = value as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(from))
+        out[key] = cloneData(from[key], depth + 1);
+    return out as T;
+}

package/src/commands.ts

@@ -1,3 +1,4 @@
+import { cloneData } from "./clone.js";
 /** Discord application command option types. */
 export const ApplicationCommandOptionEnum = {
     Subcommand: 1,
@@ -137,7 +138,7 @@ export class CreateSlashCommand {
     }
     /** Serializes the command payload. */
     public toJSON(): Record<string, unknown> {
-        return structuredClone(this.#data);
+        return cloneData(this.#data);
     }
     /** Adds a validated top-level command option. */
     protected addOption(option: CreateCommandOption): this {
@@ -174,14 +175,20 @@ export class CreateCommandOption {
         this.data.required = required;
         return this;
     }
-    /** Sets autocomplete. */
+    /** Sets autocomplete; options with choices cannot use it. */
     public setAutocomplete(enabled = true): this {
+        if (
+            enabled &&
+            Array.isArray(this.data.choices) &&
+            this.data.choices.length
+        )
+            throw new RangeError("Autocomplete options cannot define choices.");
         this.data.autocomplete = enabled;
         return this;
     }
     /** Serializes the option payload. */
     public toJSON(): Record<string, unknown> {
-        return structuredClone(this.data);
+        return cloneData(this.data);
     }
 }
 
@@ -235,6 +242,9 @@ export class CreateNumericOption extends CreateCommandOption {
             "min_value",
             this.#integer,
         );
+        const max = this.data.max_value as number | undefined;
+        if (max !== undefined && value > max)
+            throw new RangeError("min_value cannot exceed max_value.");
         this.data.min_value = value;
         return this;
     }
@@ -490,7 +500,18 @@ function appendChoices(
         throw new RangeError("Autocomplete options cannot define choices.");
     if (current.length + choices.length > 25)
         throw new RangeError("An option cannot contain more than 25 choices.");
-    for (const choice of choices) validateText(choice.name, "Choice name", 100);
+    for (const choice of choices) {
+        validateText(choice.name, "Choice name", 100);
+        const value: unknown = choice.value;
+        if (
+            typeof value === "string"
+                ? value.length === 0 || value.length > 100
+                : typeof value !== "number" || !Number.isFinite(value)
+        )
+            throw new TypeError(
+                "Choice value must be a string of 1-100 characters or a finite number.",
+            );
+    }
     data.choices = [...current, ...choices.map((choice) => ({ ...choice }))];
 }
 
@@ -596,7 +617,7 @@ export class CreateContextMenuCommand {
     }
     /** Serializes the command payload for the Discord API. */
     public toJSON(): Record<string, unknown> {
-        return structuredClone(this.data);
+        return cloneData(this.data);
     }
 }
 

package/src/components.ts

@@ -1,14 +1,17 @@
+import { cloneData } from "./clone.js";
 import { ButtonType, ComponentEnum } from "@lunibee/types";
 export { ButtonType, ComponentEnum };
 
 export const TextInputType = { Short: 1, Paragraph: 2 } as const;
 /** One {@link TextInputType} value, usable as a type. */
 export type TextInputType = (typeof TextInputType)[keyof typeof TextInputType];
+/** An emoji on a button or select option: a custom emoji `id`, or a Unicode `name`. */
 export interface APIComponentEmoji {
     id?: string | null;
     name?: string | null;
     animated?: boolean;
 }
+/** A button as a builder sends it. Exported from `lunibee` as `APIButtonPayload`. */
 export interface APIButtonComponent {
     type: typeof ComponentEnum.Button;
     style: 1 | 2 | 3 | 4 | 5 | 6;
@@ -20,6 +23,7 @@ export interface APIButtonComponent {
     sku_id?: string;
     disabled?: boolean;
 }
+/** One option of a string select menu. */
 export interface APISelectOption {
     label: string;
     value: string;
@@ -27,6 +31,7 @@ export interface APISelectOption {
     emoji?: APIComponentEmoji;
     default?: boolean;
 }
+/** A string select menu (component type 3) as Discord receives it. */
 export interface APIStringSelectComponent {
     type: typeof ComponentEnum.StringSelect;
     custom_id?: string;
@@ -37,6 +42,7 @@ export interface APIStringSelectComponent {
     disabled?: boolean;
     options?: APISelectOption[];
 }
+/** A user, role, mentionable or channel select menu as Discord receives it. */
 export interface APIEntitySelectComponent {
     type:
         | typeof ComponentEnum.UserSelect
@@ -51,6 +57,7 @@ export interface APIEntitySelectComponent {
     disabled?: boolean;
     default_values?: APISelectDefaultValue[];
 }
+/** A modal text input as a builder sends it. Exported from `lunibee` as `APITextInputPayload`. */
 export interface APITextInputComponent {
     type: typeof ComponentEnum.TextInput;
     style: typeof TextInputType.Short | typeof TextInputType.Paragraph;
@@ -62,68 +69,81 @@ export interface APITextInputComponent {
     required?: boolean;
     value?: string;
 }
+/** A modal (callback type 9 data): title, custom ID and its components. */
 export interface APIModalComponent {
     type: 9;
     custom_id: string;
     title: string;
     components: APIActionRowComponent[];
 }
+/** Any component an action row can hold: a button, a select menu or a text input. */
 export type APIActionRowChild =
     | APIButtonComponent
     | APIStringSelectComponent
     | APIEntitySelectComponent
     | APITextInputComponent;
+/** An action row as a builder sends it: up to five buttons, or one select menu or text input. Exported from `lunibee` as `APIActionRowPayload`. */
 export interface APIActionRowComponent {
     type: typeof ComponentEnum.ActionRow;
     components: APIActionRowChild[];
 }
+/** A Components V2 section: up to three text displays with an accessory. */
 export interface APISectionComponent {
     type: typeof ComponentEnum.Section;
     components?: APIComponent[]; // text displays
     accessory?: APIComponent; // buttons, thumbnails, etc.
 }
+/** A Components V2 text display (Markdown content). */
 export interface APITextDisplayComponent {
     type: typeof ComponentEnum.TextDisplay;
     content: string;
 }
+/** A Components V2 media gallery; each item is `{ media: { url }, description?, spoiler? }`. */
 export interface APIMediaGalleryComponent {
     type: typeof ComponentEnum.MediaGallery;
-    items: { media: { url: string; description?: string } }[];
+    items: {
+        media: { url: string };
+        description?: string;
+        spoiler?: boolean;
+    }[];
 }
 /** Default values accepted by an auto-populated entity select. */
 export interface APISelectDefaultValue {
     id: string;
     type: "user" | "role" | "channel";
 }
+/** A Components V2 file display for an uploaded attachment. */
 export interface APIFileComponent {
     type: typeof ComponentEnum.File;
     file: { url: string };
     spoiler?: boolean;
 }
+/** A Components V2 separator, with optional divider line and spacing. */
 export interface APISeparatorComponent {
     type: typeof ComponentEnum.Separator;
     spacing?: 1 | 2;
     divider?: boolean;
 }
+/** A Components V2 thumbnail: `{ type: 11, media: { url }, description?, spoiler? }`. */
 export interface APIThumbnailComponent {
     type: typeof ComponentEnum.Thumbnail;
-    url: string;
-    proxy_url?: string;
-    width?: number;
-    height?: number;
+    media: { url: string };
     description?: string;
     spoiler?: boolean;
 }
+/** A Components V2 content inventory entry. */
 export interface APIContentInventoryEntryComponent {
     type: typeof ComponentEnum.ContentInventoryEntry;
     id: string;
 }
+/** A Components V2 container: a box around other components, with an optional accent colour. */
 export interface APIContainerComponent {
     type: typeof ComponentEnum.Container;
     components: APIComponent[];
     accent_color?: number;
     spoiler?: boolean;
 }
+/** Any top-level message component: an action row or a Components V2 layout component. */
 export type APIComponent =
     | APIActionRowComponent
     | APIButtonComponent
@@ -253,7 +273,7 @@ export class CreateStringSelect extends CreateSelectMenu {
             throw new RangeError(
                 "max_values cannot exceed the number of options.",
             );
-        return structuredClone(this.#data);
+        return cloneData(this.#data);
     }
 }
 export class CreateButton {
@@ -301,6 +321,8 @@ export class CreateButton {
                 cause: error,
             });
         }
+        if (!["http:", "https:", "discord:"].includes(url.protocol))
+            throw new TypeError("Button URL must use http, https or discord.");
         this.setStyle(ButtonType.Link);
         this.#data.url = url.toString();
         return this;
@@ -346,7 +368,7 @@ export class CreateButton {
         }
         if (data.style !== ButtonType.Premium && !data.label && !data.emoji)
             throw new TypeError("Buttons require a label or an emoji.");
-        return structuredClone(data);
+        return cloneData(data);
     }
 }
 export class CreateEntitySelect extends CreateSelectMenu {
@@ -375,7 +397,7 @@ export class CreateEntitySelect extends CreateSelectMenu {
     }
     public toJSON(): APIEntitySelectComponent {
         assertSelect(this.#data);
-        return structuredClone(this.#data);
+        return cloneData(this.#data);
     }
 }
 export class CreateModal {
@@ -478,7 +500,7 @@ export class CreateTextInput {
             data.min_length > data.max_length
         )
             throw new RangeError("min_length cannot exceed max_length.");
-        return structuredClone(data);
+        return cloneData(data);
     }
 }
 
@@ -558,8 +580,10 @@ export class CreateTextDisplay {
 }
 
 export class CreateMediaGallery {
-    readonly #items: { media: { url: string; description?: string } }[] = [];
-    public addItems(...items: { url: string; description?: string }[]): this {
+    readonly #items: APIMediaGalleryComponent["items"] = [];
+    public addItems(
+        ...items: { url: string; description?: string; spoiler?: boolean }[]
+    ): this {
         if (!items.length) {
             throw new TypeError("At least one media gallery item is required.");
         }
@@ -568,13 +592,19 @@ export class CreateMediaGallery {
                 "MediaGallery can only contain up to 10 items.",
             );
         }
-        this.#items.push(...items.map((item) => ({ media: item })));
+        this.#items.push(
+            ...items.map(({ url, description, spoiler }) => ({
+                media: { url },
+                ...(description !== undefined ? { description } : {}),
+                ...(spoiler !== undefined ? { spoiler } : {}),
+            })),
+        );
         return this;
     }
     public toJSON(): APIMediaGalleryComponent {
         return {
             type: ComponentEnum.MediaGallery,
-            items: structuredClone(this.#items),
+            items: cloneData(this.#items),
         };
     }
 }
@@ -646,7 +676,7 @@ export class CreateThumbnail {
     public toJSON(): APIThumbnailComponent {
         const data: APIThumbnailComponent = {
             type: ComponentEnum.Thumbnail,
-            url: this.#url,
+            media: { url: this.#url },
         };
         if (this.#description !== undefined)
             data.description = this.#description;

package/src/embed.ts

@@ -1,3 +1,4 @@
+import { cloneData } from "./clone.js";
 /** Discord API embed field payload. */
 export interface EmbedField {
     /** Field name. */
@@ -171,7 +172,11 @@ export class CreateEmbed {
             throw new RangeError(
                 "Field index and delete count must be non-negative integers.",
             );
-        current.splice(index, deleteCount, ...fields);
+        for (const field of fields) {
+            validate(field.name, 256, "Embed field name");
+            validate(field.value, 1024, "Embed field value");
+        }
+        current.splice(index, deleteCount, ...fields.map((f) => ({ ...f })));
         if (current.length > 25)
             throw new RangeError(
                 "An embed cannot contain more than 25 fields.",
@@ -214,7 +219,7 @@ export class CreateEmbed {
             throw new RangeError(
                 `An embed cannot contain more than 6000 characters in total (this one has ${total}).`,
             );
-        return structuredClone(data);
+        return cloneData(data);
     }
 }
 /** Validates a bounded Discord string field. @param value Field value. @param max Maximum length. @param field Human-readable field name. @returns Validated value. @throws {RangeError} If length is invalid. */
@@ -225,9 +230,14 @@ function validate(value: string, max: number, field: string): string {
 }
 /** Validates and normalizes an absolute URL. @param value URL value. @param field Human-readable field name. @returns Normalized URL. @throws {TypeError} If URL is invalid. */
 function url(value: string, field: string): string {
+    let parsed: URL;
     try {
-        return new URL(value).toString();
+        parsed = new URL(value);
     } catch (error) {
         throw new TypeError(`${field} must be a valid URL.`, { cause: error });
     }
+    // `attachment://` points an image at an uploaded file.
+    if (!["http:", "https:", "attachment:"].includes(parsed.protocol))
+        throw new TypeError(`${field} must use http, https or attachment.`);
+    return parsed.toString();
 }