lunibee 0.3.0 → 0.3.2

package/dist/builders/attachment.d.ts

@@ -1,3 +1,4 @@
+/** 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;

package/dist/builders/clone.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 declare function cloneData<T>(value: T, depth?: number): T;

package/dist/builders/commands.d.ts

@@ -69,7 +69,7 @@ export declare class CreateCommandOption {
     setDescription(description: string): this;
     /** Makes the option required or optional. */
     setRequired(required?: boolean): this;
-    /** Sets autocomplete. */
+    /** Sets autocomplete; options with choices cannot use it. */
     setAutocomplete(enabled?: boolean): this;
     /** Serializes the option payload. */
     toJSON(): Record<string, unknown>;

package/dist/builders/components.d.ts

@@ -6,11 +6,13 @@ export declare const TextInputType: {
 };
 /** 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;
@@ -22,6 +24,7 @@ export interface APIButtonComponent {
     sku_id?: string;
     disabled?: boolean;
 }
+/** One option of a string select menu. */
 export interface APISelectOption {
     label: string;
     value: string;
@@ -29,6 +32,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;
@@ -39,6 +43,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 | typeof ComponentEnum.RoleSelect | typeof ComponentEnum.MentionableSelect | typeof ComponentEnum.ChannelSelect;
     custom_id?: string;
@@ -49,6 +54,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;
@@ -60,33 +66,40 @@ 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[];
     accessory?: APIComponent;
 }
+/** 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;
         };
+        description?: string;
+        spoiler?: boolean;
     }[];
 }
 /** Default values accepted by an auto-populated entity select. */
@@ -94,6 +107,7 @@ 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: {
@@ -101,30 +115,34 @@ export interface APIFileComponent {
     };
     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 | APIStringSelectComponent | APIEntitySelectComponent | APITextInputComponent | APISectionComponent | APITextDisplayComponent | APIThumbnailComponent | APIMediaGalleryComponent | APIFileComponent | APISeparatorComponent | APIContentInventoryEntryComponent | APIContainerComponent;
 export declare class CreateActionRow<T extends {
     toJSON(): APIActionRowChild;
@@ -225,6 +243,7 @@ export declare class CreateMediaGallery {
     addItems(...items: {
         url: string;
         description?: string;
+        spoiler?: boolean;
     }[]): this;
     toJSON(): APIMediaGalleryComponent;
 }

package/dist/builders/embed.d.ts

@@ -90,5 +90,6 @@ export declare class CreateEmbed {
     clearDescription(): this;
     /** Returns a deep-cloned Discord API payload. @returns Strict embed payload. */
     get data(): APIEmbed;
+    /** Returns a deep-cloned Discord API payload. @returns Strict embed payload. @throws {RangeError} If the text in the embed adds up to more than Discord's 6000-character limit. */
     toJSON(): APIEmbed;
 }

package/dist/builders/index.js

@@ -1,4 +1,26 @@
 // @bun
+// packages/builders/src/clone.ts
+function cloneData(value, depth = 0) {
+  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;
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null)
+    return structuredClone(value);
+  const from = value;
+  const out = {};
+  for (const key of Object.keys(from))
+    out[key] = cloneData(from[key], depth + 1);
+  return out;
+}
+
 // packages/builders/src/embed.ts
 class CreateEmbed {
   #data = {};
@@ -94,7 +116,11 @@ class CreateEmbed {
     const current = [...this.#data.fields ?? []];
     if (!Number.isInteger(index) || !Number.isInteger(deleteCount) || index < 0 || deleteCount < 0)
       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.");
     this.#data.fields = current;
@@ -116,7 +142,11 @@ class CreateEmbed {
     return this.toJSON();
   }
   toJSON() {
-    return structuredClone(this.#data);
+    const data = this.#data;
+    const total = (data.title?.length ?? 0) + (data.description?.length ?? 0) + (data.footer?.text.length ?? 0) + (data.author?.name.length ?? 0) + (data.fields ?? []).reduce((sum, field) => sum + field.name.length + field.value.length, 0);
+    if (total > 6000)
+      throw new RangeError(`An embed cannot contain more than 6000 characters in total (this one has ${total}).`);
+    return cloneData(data);
   }
 }
 function validate(value, max, field) {
@@ -125,11 +155,15 @@ function validate(value, max, field) {
   return value;
 }
 function url(value, field) {
+  let parsed;
   try {
-    return new URL(value).toString();
+    parsed = new URL(value);
   } catch (error) {
     throw new TypeError(`${field} must be a valid URL.`, { cause: error });
   }
+  if (!["http:", "https:", "attachment:"].includes(parsed.protocol))
+    throw new TypeError(`${field} must use http, https or attachment.`);
+  return parsed.toString();
 }
 // packages/types/src/channel-kind.ts
 var ChannelKinds = {
@@ -323,7 +357,7 @@ class CreateStringSelect extends CreateSelectMenu {
       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);
+    return cloneData(this.#data);
   }
 }
 
@@ -371,6 +405,8 @@ 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;
@@ -409,7 +445,7 @@ 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);
   }
 }
 
@@ -428,7 +464,7 @@ class CreateEntitySelect extends CreateSelectMenu {
   }
   toJSON() {
     assertSelect(this.#data);
-    return structuredClone(this.#data);
+    return cloneData(this.#data);
   }
 }
 
@@ -520,7 +556,7 @@ class CreateTextInput {
       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);
+    return cloneData(data);
   }
 }
 
@@ -604,13 +640,17 @@ class CreateMediaGallery {
     if (this.#items.length + items.length > 10) {
       throw new RangeError("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;
   }
   toJSON() {
     return {
       type: ComponentEnum.MediaGallery,
-      items: structuredClone(this.#items)
+      items: cloneData(this.#items)
     };
   }
 }
@@ -684,7 +724,7 @@ class CreateThumbnail {
   toJSON() {
     const data = {
       type: ComponentEnum.Thumbnail,
-      url: this.#url
+      media: { url: this.#url }
     };
     if (this.#description !== undefined)
       data.description = this.#description;
@@ -849,7 +889,7 @@ class CreateSlashCommand {
     return this.addOption(configure(new CreateSubcommandGroup));
   }
   toJSON() {
-    return structuredClone(this.#data);
+    return cloneData(this.#data);
   }
   addOption(option) {
     this.#data.options = appendOption(this.#data.options, option.toJSON(), "application command");
@@ -877,11 +917,13 @@ class CreateCommandOption {
     return this;
   }
   setAutocomplete(enabled = true) {
+    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;
   }
   toJSON() {
-    return structuredClone(this.data);
+    return cloneData(this.data);
   }
 }
 
@@ -917,6 +959,9 @@ class CreateNumericOption extends CreateCommandOption {
   }
   setMinValue(value) {
     validateNumberRange(value, -MAX_SAFE, MAX_SAFE, "min_value", this.#integer);
+    const max = this.data.max_value;
+    if (max !== undefined && value > max)
+      throw new RangeError("min_value cannot exceed max_value.");
     this.data.min_value = value;
     return this;
   }
@@ -1071,8 +1116,12 @@ function appendChoices(data, choices) {
     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)
+  for (const choice of choices) {
     validateText2(choice.name, "Choice name", 100);
+    const value = 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 }))];
 }
 function validateName(value, field) {
@@ -1127,7 +1176,7 @@ class CreateContextMenuCommand {
     return this;
   }
   toJSON() {
-    return structuredClone(this.data);
+    return cloneData(this.data);
   }
 }
 
@@ -1194,12 +1243,14 @@ class CreateAttachment {
   }
 }
 async function insideRoot(root, file) {
-  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;
 }
@@ -1248,4 +1299,4 @@ export {
   componentsV2Message
 };
 
-//# debugId=C9A7870D27CD731F64756E2164756E21
+//# debugId=53A00A51A367F67A64756E2164756E21