lunibee 0.1.8 → 0.2.1

package/README.md

@@ -130,6 +130,8 @@ Resource managers maintain canonical instances by Discord resource ID. Re-resolv
 
 REST-created and Gateway-updated resources are routed through manager cache mutation APIs so the same resource is not represented by unrelated structure instances.
 
+Discord resources are stored with `Collection.setWithoutTTL()` and leave the cache only through Gateway delete events or an explicit `delete()`, never through expiry. Messages are cached only with the `messageCache: { maxSize?, ttl? }` client option, and `cache: { users, members, roles, emojis }` turns off per-resource caching on large bots. For your own data, `new Collection(null, { ttl, maxSize, onEvict })` is a TTL/LRU cache. See the [0.2.0 upgrade guide](https://lunibee.js.org/getting-started/upgrading/).
+
 ## Permissions
 
 `PermissionSet` provides named and raw permission checks:

package/dist/builders/components.d.ts

@@ -23,6 +23,10 @@ export declare const TextInputStyle: {
     readonly Short: 1;
     readonly Paragraph: 2;
 };
+/** 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 +39,8 @@ export interface APIButtonComponent {
     label?: string;
     emoji?: APIComponentEmoji;
     url?: string;
+    /** SKU for premium (style 6) buttons. */
+    sku_id?: string;
     disabled?: boolean;
 }
 export interface APISelectOption {
@@ -77,8 +83,8 @@ export interface APITextInputComponent {
 }
 export interface APIModalComponent {
     type: 9;
-    custom_id?: string;
-    title?: string;
+    custom_id: string;
+    title: string;
     components: APIActionRowComponent[];
 }
 export type APIActionRowChild = APIButtonComponent | APIStringSelectComponent | APIEntitySelectComponent | APITextInputComponent;
@@ -164,10 +170,13 @@ export declare class StringSelectBuilder {
 }
 export declare class ButtonBuilder {
     #private;
+    /** Sets the style and drops fields that style cannot carry. */
     setStyle(style: APIButtonComponent["style"]): this;
     setCustomId(value: string): this;
     setLabel(value: string): this;
     setURL(value: string): this;
+    /** Makes this a premium (purchase) button for a SKU. Premium buttons carry no label, emoji, custom ID or URL. */
+    setSKUId(skuId: string): this;
     setEmoji(emoji: APIComponentEmoji | string): this;
     setDisabled(value?: boolean): this;
     toJSON(): APIButtonComponent;
@@ -191,6 +200,8 @@ export declare class ModalBuilder {
     addComponents(...components: Array<{
         toJSON(): APIActionRowComponent;
     }>): this;
+    /** Adds text inputs, each in its own action row (Discord's modal layout). @param inputs Text inputs, at most 5 per modal. */
+    addTextInputs(...inputs: TextInputBuilder[]): this;
     toJSON(): APIModalComponent;
 }
 export declare class TextInputBuilder {
@@ -282,3 +293,20 @@ export declare class MentionableSelectMenuBuilder extends EntitySelectBuilder {
 export declare class ChannelSelectMenuBuilder extends EntitySelectBuilder {
     constructor();
 }
+/**
+ * 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 declare 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;

package/dist/builders/embed.d.ts

@@ -35,19 +35,19 @@ export interface APIEmbed {
 /** Builds compile-time-safe rich embed payloads for Discord API requests. */
 export declare class EmbedBuilder {
     #private;
-    /** Sets the embed title. @param value Title text. @returns This builder. @throws {RangeError} If title exceeds Discord's limit. */ setTitle(value: string): this;
-    /** Sets the embed description. @param value Description text. @returns This builder. @throws {RangeError} If description exceeds Discord's limit. */ setDescription(value: string): this;
-    /** Sets the embed URL. @param value Absolute URL. @returns This builder. @throws {TypeError} If URL is invalid. */ setURL(value: string): this;
+    /** Sets the embed title. @param value Title text, or null to clear. @returns This builder. @throws {RangeError} If title exceeds Discord's limit. */ setTitle(value: string | null): this;
+    /** Sets the embed description. @param value Description text, or null to clear. @returns This builder. @throws {RangeError} If description exceeds Discord's limit. */ setDescription(value: string | null): this;
+    /** Sets the embed URL. @param value Absolute URL, or null to clear. @returns This builder. @throws {TypeError} If URL is invalid. */ setURL(value: string | null): this;
     /** Sets the embed color. @param value RGB integer. @returns This builder. @throws {RangeError} If color is outside 24-bit RGB range. */ setColor(value: number): this;
     /** Sets the embed timestamp. @param value Date value. @returns This builder. @throws {RangeError} If date is invalid. */ setTimestamp(value?: Date): this;
     /** Sets the embed footer. @param value Footer payload. @returns This builder. @throws {RangeError} If footer text exceeds Discord's limit. */ setFooter(value: EmbedFooter): this;
     /** Sets the embed author. @param value Author payload. @returns This builder. @throws {RangeError} If author name exceeds Discord's limit. */ setAuthor(value: EmbedAuthor): this;
-    /** Sets the thumbnail URL. @param value Thumbnail URL or payload. @returns This builder. @throws {TypeError} If URL is invalid. */ setThumbnail(value: {
+    /** Sets the thumbnail URL. @param value Thumbnail URL or payload, or null to clear. @returns This builder. @throws {TypeError} If URL is invalid. */ setThumbnail(value: {
         url: string;
-    } | string): this;
-    /** Sets the image URL. @param value Image URL or payload. @returns This builder. @throws {TypeError} If URL is invalid. */ setImage(value: {
+    } | string | null): this;
+    /** Sets the image URL. @param value Image URL or payload, or null to clear. @returns This builder. @throws {TypeError} If URL is invalid. */ setImage(value: {
         url: string;
-    } | string): this;
+    } | string | null): this;
     /** Adds embed fields. Accepts both the spread form `addFields(a, b)` and the
      * single-array form `addFields([a, b])` for discord.js `RestOrArray` parity.
      * @param fields Field payloads, spread or as a single array. @returns This builder. @throws {RangeError} If the 25-field limit is exceeded. */ addFields(...fields: EmbedField[] | [EmbedField[]]): this;

package/dist/builders/index.d.ts

@@ -1,5 +1,5 @@
 export { EmbedBuilder } from "./embed.js";
 export type { EmbedField } from "./embed.js";
-export { ButtonBuilder, ButtonStyle, ComponentType, ActionRowBuilder, StringSelectBuilder, StringSelectMenuBuilder, EntitySelectBuilder, UserSelectMenuBuilder, RoleSelectMenuBuilder, MentionableSelectMenuBuilder, ChannelSelectMenuBuilder, ModalBuilder, TextInputBuilder, TextInputStyle, ContainerBuilder, SectionBuilder, TextDisplayBuilder, MediaGalleryBuilder, FileComponentBuilder, SeparatorBuilder, ThumbnailBuilder, ContentInventoryEntryBuilder, } from "./components.js";
+export { ButtonBuilder, ButtonStyle, ComponentType, ActionRowBuilder, StringSelectBuilder, StringSelectMenuBuilder, EntitySelectBuilder, UserSelectMenuBuilder, RoleSelectMenuBuilder, MentionableSelectMenuBuilder, ChannelSelectMenuBuilder, ModalBuilder, TextInputBuilder, TextInputStyle, ContainerBuilder, SectionBuilder, TextDisplayBuilder, MediaGalleryBuilder, FileComponentBuilder, SeparatorBuilder, ThumbnailBuilder, ContentInventoryEntryBuilder, componentsV2Message, } from "./components.js";
 export { SlashCommandBuilder, StringOptionBuilder, IntegerOptionBuilder, NumberOptionBuilder, BooleanOptionBuilder, UserOptionBuilder, ChannelOptionBuilder, RoleOptionBuilder, MentionableOptionBuilder, AttachmentOptionBuilder, SubcommandBuilder, SubcommandGroupBuilder, ApplicationCommandOptionType, UserCommandBuilder, MessageCommandBuilder, ContextMenuCommandBuilder, } from "./commands.js";
 export { AttachmentBuilder, type AttachmentData } from "./attachment.js";

package/dist/builders/index.js

@@ -3,15 +3,24 @@
 class EmbedBuilder {
   #data = {};
   setTitle(value) {
-    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;
   }
   setDescription(value) {
-    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;
   }
   setURL(value) {
-    this.#data.url = url(value, "Embed URL");
+    if (value === null)
+      delete this.#data.url;
+    else
+      this.#data.url = url(value, "Embed URL");
     return this;
   }
   setColor(value) {
@@ -43,11 +52,19 @@ class EmbedBuilder {
     return this;
   }
   setThumbnail(value) {
+    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;
   }
   setImage(value) {
+    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;
@@ -212,10 +229,13 @@ class ActionRowBuilder {
     return this;
   }
   toJSON() {
-    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 };
   }
 }
 
@@ -270,6 +290,12 @@ class StringSelectBuilder {
     return this;
   }
   toJSON() {
+    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);
   }
 }
@@ -280,9 +306,20 @@ class ButtonBuilder {
     style: ButtonStyle.Secondary
   };
   setStyle(style) {
-    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;
   }
   setCustomId(value) {
@@ -307,11 +344,16 @@ 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;
   }
+  setSKUId(skuId) {
+    validateText(skuId, 20, "Button SKU ID");
+    this.setStyle(ButtonStyle.Premium);
+    this.#data.sku_id = skuId;
+    return this;
+  }
   setEmoji(emoji) {
     this.#data.emoji = typeof emoji === "string" ? { name: emoji } : { ...emoji };
     return this;
@@ -321,7 +363,26 @@ class ButtonBuilder {
     return this;
   }
   toJSON() {
-    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);
   }
 }
 
@@ -365,6 +426,7 @@ class EntitySelectBuilder {
     return this;
   }
   toJSON() {
+    assertSelect(this.#data);
     return structuredClone(this.#data);
   }
 }
@@ -391,11 +453,18 @@ class ModalBuilder {
     this.#components.push(...components);
     return this;
   }
+  addTextInputs(...inputs) {
+    return this.addComponents(...inputs.map((input) => new ActionRowBuilder().addComponents(input)));
+  }
   toJSON() {
+    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())
     };
   }
@@ -445,7 +514,12 @@ class TextInputBuilder {
     return this;
   }
   toJSON() {
-    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);
   }
 }
 
@@ -672,6 +746,23 @@ class ChannelSelectMenuBuilder extends EntitySelectBuilder {
     super(ComponentType.ChannelSelect);
   }
 }
+function assertSelect(data) {
+  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.");
+}
+var IS_COMPONENTS_V2 = 1 << 15;
+function componentsV2Message(components, options) {
+  const list = Array.isArray(components) ? components : [components];
+  if (!list.length)
+    throw new TypeError("A Components V2 message needs at least one component.");
+  return {
+    ...options ?? {},
+    components: list.map((component) => component.toJSON()),
+    flags: (options?.flags ?? 0) | IS_COMPONENTS_V2
+  };
+}
 // packages/builders/src/commands.ts
 var ApplicationCommandOptionType = {
   Subcommand: 1,
@@ -1161,7 +1252,8 @@ export {
   ThumbnailBuilder,
   UserCommandBuilder,
   UserOptionBuilder,
-  UserSelectMenuBuilder
+  UserSelectMenuBuilder,
+  componentsV2Message
 };
 
-//# debugId=51C5BC8CB8846ABF64756E2164756E21
+//# debugId=8C8B25AA416C8B5064756E2164756E21