gralonium 0.2.0

package/lib/classes/builders/CommandBuilder.d.ts

@@ -0,0 +1,50 @@
+export declare function validateDefaultMemberPermissions(permissions: unknown): string | null | undefined;
+
+export interface CommandDataBuilder {
+  name: string;
+  aliases?: string[];
+  description?: string;
+  as_prefix?: boolean;
+  as_slash?: boolean;
+  fallback?: true;
+  guildOnly?: boolean;
+  multiple_args?: boolean;
+  defaultMemberPermissions?: string | bigint;
+  userPermissions?: string[];
+  botPermissions?: string[];
+  guards?: Array<(ctx: any) => boolean | Promise<boolean>>;
+  cooldown?: { seconds: number; bucket?: string };
+}
+
+export declare class CommandBuilder {
+  name: string;
+  aliases: string[];
+  description: string;
+  as_prefix: boolean;
+  as_slash: boolean;
+  fallback: boolean;
+  guildOnly: boolean | undefined;
+  multiple_args?: boolean;
+  defaultMemberPermissions?: string | bigint | undefined;
+  userPermissions: string[];
+  botPermissions: string[];
+  guards: Array<(ctx: any) => boolean | Promise<boolean>>;
+  cooldown?: { seconds: number; bucket?: string };
+  constructor(options?: CommandDataBuilder);
+  setName(name: string): CommandBuilder;
+  setDescription(description: string): CommandBuilder;
+  setAliases(...aliases: string[]): CommandBuilder;
+  allowPrefix(allow: boolean): CommandBuilder;
+  allowSlash(allow: boolean): CommandBuilder;
+  allowMultipleArgs(allow: boolean): CommandBuilder;
+  setGuards(...guards: Array<(ctx: any) => boolean | Promise<boolean>>): CommandBuilder;
+  setUserPermissions(...permissions: string[]): CommandBuilder;
+  setBotPermissions(...permissions: string[]): CommandBuilder;
+  setCooldown(seconds: number, bucket?: string): CommandBuilder;
+  toJSON(): {
+    name: string;
+    description: string;
+    default_member_permissions: string | null | undefined;
+    dm_permission: boolean | undefined;
+  };
+}

package/lib/classes/builders/CommandBuilder.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandBuilder = exports.validateDefaultMemberPermissions = void 0;
+
+const shapeshift_1 = require("@sapphire/shapeshift");
+
+const memberPermissionPredicate = shapeshift_1.s
+  .union(shapeshift_1.s.bigint.transform((value) => value.toString()), shapeshift_1.s.number.safeInt.transform((value) => value.toString()), shapeshift_1.s.string.regex(/^\d+$/))
+  .nullish;
+const permissionStringPredicate = shapeshift_1.s.string.lengthGreaterThan(0);
+const permissionArrayPredicate = shapeshift_1.s.array(permissionStringPredicate);
+
+function validateDefaultMemberPermissions(permissions) {
+  return memberPermissionPredicate.parse(permissions);
+}
+exports.validateDefaultMemberPermissions = validateDefaultMemberPermissions;
+
+class CommandBuilder {
+  name;
+  aliases;
+  description;
+  as_prefix;
+  as_slash;
+  fallback;
+  guildOnly;
+  multiple_args;
+  defaultMemberPermissions;
+  userPermissions;
+  botPermissions;
+  guards;
+  cooldown;
+
+  constructor(options) {
+    this.name = options?.name ?? "";
+    this.aliases = options?.aliases ?? [];
+    this.description = options?.description ?? "...";
+    this.fallback = options?.fallback ?? false;
+    this.as_prefix = options?.as_prefix ?? true;
+    this.as_slash = options?.as_slash ?? true;
+    this.guildOnly = options?.guildOnly;
+    this.defaultMemberPermissions = options?.defaultMemberPermissions;
+    this.userPermissions = permissionArrayPredicate.parse(options?.userPermissions ?? []);
+    this.botPermissions = permissionArrayPredicate.parse(options?.botPermissions ?? []);
+    this.guards = options?.guards ?? [];
+    this.cooldown = options?.cooldown;
+  }
+
+  setName(name) {
+    this.name = name;
+    return this;
+  }
+
+  setDescription(description) {
+    this.description = description;
+    return this;
+  }
+
+  setAliases(...aliases) {
+    this.aliases = aliases;
+    return this;
+  }
+
+  allowPrefix(allow) {
+    this.as_prefix = allow;
+    return this;
+  }
+
+  allowSlash(allow) {
+    this.as_slash = allow;
+    return this;
+  }
+
+  allowMultipleArgs(allow) {
+    this.multiple_args = allow;
+    return this;
+  }
+
+  setGuards(...guards) {
+    this.guards = guards;
+    return this;
+  }
+
+  setUserPermissions(...permissions) {
+    this.userPermissions = permissionArrayPredicate.parse(permissions);
+    return this;
+  }
+
+  setBotPermissions(...permissions) {
+    this.botPermissions = permissionArrayPredicate.parse(permissions);
+    return this;
+  }
+
+  setCooldown(seconds, bucket = "USER") {
+    this.cooldown = { seconds, bucket };
+    return this;
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      description: this.description,
+      default_member_permissions: this.defaultMemberPermissions ? validateDefaultMemberPermissions(this.defaultMemberPermissions) : undefined,
+      dm_permission: typeof this.guildOnly === "boolean" ? !this.guildOnly : undefined,
+    };
+  }
+}
+exports.CommandBuilder = CommandBuilder;

package/lib/classes/builders/ComponentsV2Builder.d.ts

@@ -0,0 +1,125 @@
+import {
+  ButtonBuilder,
+  ButtonStyle,
+  ContainerBuilder,
+  MessageFlags,
+} from "discord.js";
+import { ButtonStyleInput } from "./components/StyleMapper.js";
+
+/**
+ * Fluent proxy returned by `ComponentsV2Builder#addSelectMenu()`.
+ * Call `.end()` to return to the parent builder.
+ */
+export declare class SelectMenuProxy {
+  /**
+   * Add an option to the select menu.
+   *
+   * @param label       - Display label for the option
+   * @param value       - Value submitted when the option is selected
+   * @param emoji       - Unicode emoji (optional)
+   * @param description - Short description shown below the label (optional)
+   */
+  addOption(label: string, value?: string, emoji?: string, description?: string): this;
+
+  /** Return to the parent `ComponentsV2Builder`. */
+  end(): ComponentsV2Builder;
+}
+
+/**
+ * ComponentsV2Builder — a fluent builder that abstracts the complexity of
+ * Discord.js Components V2 (Containers, Separators, TextDisplays, Buttons,
+ * and StringSelectMenus).
+ *
+ * @example
+ * ```ts
+ * const components = new ComponentsV2Builder()
+ *   .addText("## Welcome!")
+ *   .addSeparator("small")
+ *   .addButton("Click Me", "btn_1", "primary")
+ *   .addButton("Cancel", "btn_2", "secondary")
+ *   .build();
+ *
+ * interaction.reply({ components, flags: ComponentsV2Builder.flags });
+ * ```
+ */
+export declare class ComponentsV2Builder {
+  /**
+   * Add a text display (markdown supported) to the container.
+   */
+  addText(content: string): this;
+
+  /**
+   * Add a separator to the container.
+   *
+   * @param spacing - "small" | "large" (defaults to "small")
+   * @param divider - Whether to render a visual divider line (defaults to true)
+   */
+  addSeparator(spacing?: "small" | "large", divider?: boolean): this;
+
+  /**
+   * Add a single button to the container.
+   * Buttons are batched and placed into ActionRows automatically (max 5 per row).
+   *
+   * @param label    - Button label text
+   * @param customId - Custom ID (or URL for link buttons)
+   * @param style    - "primary" | "secondary" | "success" | "danger" | "link"
+   * @param url      - URL (only used when style is "link")
+   */
+  addButton(label: string, customId?: string, style?: ButtonStyleInput, url?: string): this;
+
+  /**
+   * Add multiple pre-built `ButtonBuilder` instances at once.
+   * They are batched into ActionRows automatically (max 5 per row).
+   */
+  addButtons(...buttons: ButtonBuilder[]): this;
+
+  /**
+   * Add a `StringSelectMenu` to the container.
+   * Returns a `SelectMenuProxy` for adding options fluently.
+   * Call `.end()` on the proxy to return to this builder.
+   *
+   * @param customId    - Custom ID for the select menu
+   * @param placeholder - Placeholder text (optional)
+   */
+  addSelectMenu(customId?: string, placeholder?: string): SelectMenuProxy;
+
+  /**
+   * Mark the container as a spoiler (blurred until clicked).
+   */
+  setSpoiler(spoiler: boolean): this;
+
+  /**
+   * Build and return the components array ready for
+   * `interaction.reply({ components: builder.build(), flags: ComponentsV2Builder.flags })`.
+   */
+  build(): ContainerBuilder[];
+
+  /**
+   * The `MessageFlags` bitmask required for Components V2 messages.
+   *
+   * ```ts
+   * interaction.reply({ components: builder.build(), flags: ComponentsV2Builder.flags });
+   * ```
+   */
+  static readonly flags: MessageFlags;
+
+  /**
+   * Create a Confirm / Cancel button container.
+   */
+  static createConfirm(confirmId?: string, cancelId?: string): ComponentsV2Builder;
+
+  /**
+   * Create a ticket category select menu container.
+   */
+  static createTicketMenu(customId?: string): ComponentsV2Builder;
+
+  /**
+   * Create a plan selector container (bot / game / web hosting example).
+   */
+  static createPlanSelector(customId?: string): ComponentsV2Builder;
+
+  /**
+   * Create a role selector menu container.
+   */
+  static createRoleMenu(customId?: string): ComponentsV2Builder;
+}

package/lib/classes/builders/ComponentsV2Builder.js

@@ -0,0 +1,287 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ComponentsV2Builder = void 0;
+
+const discord_js_1 = require("discord.js");
+const StyleMapper_js_1 = require("./components/StyleMapper.js");
+const helpers_js_1 = require("./components/helpers.js");
+
+/**
+ * SelectMenuProxy gives a chainable API to add options to a StringSelectMenu
+ * and then return to the parent ComponentsV2Builder via `.end()`.
+ */
+class SelectMenuProxy {
+  constructor(parent, menu) {
+    this._parent = parent;
+    this._menu = menu;
+    this._optionCount = 0;
+  }
+
+  /**
+   * Add an option to the select menu.
+   */
+  addOption(label, value, emoji, description) {
+    this._optionCount += 1;
+    helpers_js_1.validateSelectMenuOptions(this._optionCount);
+
+    const option = new discord_js_1.StringSelectMenuOptionBuilder()
+      .setLabel(label)
+      .setValue(value ?? helpers_js_1.generateCustomId("opt"));
+
+    if (emoji) option.setEmoji({ name: emoji });
+    if (description) option.setDescription(description);
+
+    this._menu.addOptions(option);
+    return this;
+  }
+
+  /**
+   * Return to the parent builder to continue chaining.
+   */
+  end() {
+    return this._parent;
+  }
+}
+
+/**
+ * ComponentsV2Builder — a fluent builder that abstracts the complexity of
+ * Discord.js Components V2 (Containers, Separators, TextDisplays, Buttons,
+ * and StringSelectMenus).
+ *
+ * @example
+ * ```js
+ * const { ComponentsV2Builder } = require("gralonium");
+ *
+ * const components = new ComponentsV2Builder()
+ *   .addText("## Welcome!")
+ *   .addSeparator("small")
+ *   .addButton("Click Me", "btn_1", "primary")
+ *   .addButton("Cancel", "btn_2", "secondary")
+ *   .build();
+ *
+ * interaction.reply({ components });
+ * ```
+ */
+class ComponentsV2Builder {
+  constructor() {
+    this._container = new discord_js_1.ContainerBuilder();
+    this._pendingButtons = [];
+    this._spoiler = false;
+  }
+
+  // ─── Internal helpers ────────────────────────────────────────────────────
+
+  /**
+   * Flush any pending buttons into an ActionRow inside the container.
+   */
+  _flushButtons() {
+    if (this._pendingButtons.length === 0) return;
+    const row = new discord_js_1.ActionRowBuilder().addComponents(...this._pendingButtons);
+    this._container.addActionRowComponents(row);
+    this._pendingButtons = [];
+  }
+
+  // ─── Public API ──────────────────────────────────────────────────────────
+
+  /**
+   * Add a text display (markdown supported) to the container.
+   */
+  addText(content) {
+    helpers_js_1.validateTextContent(content);
+    this._flushButtons();
+    this._container.addTextDisplayComponents(
+      new discord_js_1.TextDisplayBuilder().setContent(content)
+    );
+    return this;
+  }
+
+  /**
+   * Add a separator to the container.
+   *
+   * @param spacing - "small" | "large" (defaults to "small")
+   * @param divider - Whether to render a visual divider line (defaults to true)
+   */
+  addSeparator(spacing, divider) {
+    this._flushButtons();
+    const spacingValue =
+      spacing === "large"
+        ? discord_js_1.SeparatorSpacingSize.Large
+        : discord_js_1.SeparatorSpacingSize.Small;
+    const sep = new discord_js_1.SeparatorBuilder()
+      .setSpacing(spacingValue)
+      .setDivider(divider !== false);
+    this._container.addSeparatorComponents(sep);
+    return this;
+  }
+
+  /**
+   * Add a single button to the container.
+   * Buttons are batched and placed into ActionRows automatically (max 5 per row).
+   *
+   * @param label     - Button label text
+   * @param customId  - Custom ID (or URL for link buttons)
+   * @param style     - "primary" | "secondary" | "success" | "danger" | "link"
+   * @param url       - URL (only used when style is "link")
+   */
+  addButton(label, customId, style, url) {
+    const resolvedStyle = StyleMapper_js_1.mapButtonStyle(style);
+
+    // If we already have 5 buttons pending, flush them first
+    if (this._pendingButtons.length >= 5) {
+      this._flushButtons();
+    }
+
+    const btn = new discord_js_1.ButtonBuilder()
+      .setLabel(label)
+      .setStyle(resolvedStyle);
+
+    if (resolvedStyle === discord_js_1.ButtonStyle.Link) {
+      if (!url) throw new Error("[ComponentsV2Builder] A link button requires a URL.");
+      if (customId) {
+        console.warn("[ComponentsV2Builder] customId is ignored for link buttons; use the 'url' parameter instead.");
+      }
+      btn.setURL(url);
+    } else {
+      btn.setCustomId(customId ?? helpers_js_1.generateCustomId("btn"));
+    }
+
+    this._pendingButtons.push(btn);
+    return this;
+  }
+
+  /**
+   * Add multiple pre-built ButtonBuilder instances at once.
+   * They are batched into ActionRows automatically (max 5 per row).
+   */
+  addButtons(...buttons) {
+    for (const btn of buttons) {
+      if (this._pendingButtons.length >= 5) {
+        this._flushButtons();
+      }
+      this._pendingButtons.push(btn);
+    }
+    return this;
+  }
+
+  /**
+   * Add a StringSelectMenu to the container and return a SelectMenuProxy
+   * for adding options via a fluent sub-chain. Call `.end()` on the proxy
+   * to return to this builder.
+   *
+   * @param customId    - Custom ID for the select menu
+   * @param placeholder - Placeholder text (optional)
+   */
+  addSelectMenu(customId, placeholder) {
+    this._flushButtons();
+    const menu = new discord_js_1.StringSelectMenuBuilder()
+      .setCustomId(customId ?? helpers_js_1.generateCustomId("sel"))
+      .setPlaceholder(placeholder ?? "Select an option...");
+
+    // We need to add the row after options are configured; the proxy returns
+    // to us via `.end()` which flushes remaining buttons and adds the row.
+    // To support immediate chaining, we attach the row now — options get added
+    // by the proxy in-place (discord.js builders are mutable).
+    const row = new discord_js_1.ActionRowBuilder().addComponents(menu);
+    this._container.addActionRowComponents(row);
+    return new SelectMenuProxy(this, menu);
+  }
+
+  /**
+   * Mark the container as a spoiler (blurred until clicked).
+   */
+  setSpoiler(spoiler) {
+    this._spoiler = spoiler;
+    this._container.setSpoiler(spoiler);
+    return this;
+  }
+
+  /**
+   * Build and return the components array ready to pass to
+   * `interaction.reply({ components })`.
+   *
+   * The `MessageFlags.IsComponentsV2` flag is **not** added here because it
+   * must be set on the reply options object itself, not inside the components
+   * array. Use the helper `ComponentsV2Builder.flags` constant when replying:
+   *
+   * ```js
+   * interaction.reply({ components: builder.build(), flags: ComponentsV2Builder.flags });
+   * ```
+   */
+  build() {
+    this._flushButtons();
+    return [this._container];
+  }
+
+  // ─── Static helpers ──────────────────────────────────────────────────────
+
+  /**
+   * The MessageFlags bitmask required for Components V2 messages.
+   *
+   * ```js
+   * interaction.reply({ components: builder.build(), flags: ComponentsV2Builder.flags });
+   * ```
+   */
+  static get flags() {
+    return discord_js_1.MessageFlags.IsComponentsV2;
+  }
+
+  // ─── Quick Templates ─────────────────────────────────────────────────────
+
+  /**
+   * Create a Confirm / Cancel button container.
+   *
+   * @param confirmId - Custom ID for the confirm button (default: "cv2_confirm")
+   * @param cancelId  - Custom ID for the cancel button (default: "cv2_cancel")
+   */
+  static createConfirm(confirmId, cancelId) {
+    return new ComponentsV2Builder()
+      .addText("**Are you sure?**")
+      .addSeparator("small")
+      .addButton("Confirm", confirmId ?? "cv2_confirm", "success")
+      .addButton("Cancel", cancelId ?? "cv2_cancel", "danger");
+  }
+
+  /**
+   * Create a ticket category select menu container.
+   *
+   * @param customId - Custom ID for the select menu (default: "cv2_ticket_menu")
+   */
+  static createTicketMenu(customId) {
+    return new ComponentsV2Builder()
+      .addText("## 🎫 Open a Ticket")
+      .addSeparator("small")
+      .addSelectMenu(customId ?? "cv2_ticket_menu", "Select a category...")
+        .addOption("General Support", "ticket_general", "❓")
+        .addOption("Billing", "ticket_billing", "💳")
+        .addOption("Technical Issue", "ticket_tech", "🔧")
+        .end();
+  }
+
+  /**
+   * Create a plan selector container (bot / game / web hosting example).
+   *
+   * @param customId - Custom ID for the select menu (default: "cv2_plan_menu")
+   */
+  static createPlanSelector(customId) {
+    return new ComponentsV2Builder()
+      .addText("## Welcome!\nPlease select the plan you want to join!")
+      .addSeparator("small")
+      .addButton("Discord Bot Hosting", "plan_bot", "primary")
+      .addButton("Game Hosting", "plan_game", "success")
+      .addButton("Web Hosting", "plan_web", "danger");
+  }
+
+  /**
+   * Create a role selector menu container.
+   *
+   * @param customId - Custom ID for the select menu (default: "cv2_role_menu")
+   */
+  static createRoleMenu(customId) {
+    return new ComponentsV2Builder()
+      .addText("## 🎭 Select a Role")
+      .addSeparator("small")
+      .addSelectMenu(customId ?? "cv2_role_menu", "Choose your role...")
+        .end();
+  }
+}
+exports.ComponentsV2Builder = ComponentsV2Builder;

package/lib/classes/builders/EventBuilder.d.ts

@@ -0,0 +1,19 @@
+import { ClientEvents } from "discord.js";
+export interface EventDataBuilder {
+    name: keyof ClientEvents;
+    once: boolean;
+    description?: string;
+}
+export declare class EventBuilder {
+    name: string;
+    once: boolean;
+    description: string;
+    constructor(options?: EventDataBuilder);
+    /**
+     * Returns the command data parsed as JSON.
+     */
+    toJSON(): {
+        name: string;
+        description: string;
+    };
+}

package/lib/classes/builders/EventBuilder.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.EventBuilder=void 0;class EventBuilder{name;once;description;constructor(e){this.name=e?.name??"",this.once=e?.once??!1,this.description=e?.description??"..."}toJSON(){return{name:this.name,description:this.description}}}exports.EventBuilder=EventBuilder;

package/lib/classes/builders/GroupBuilder.d.ts

@@ -0,0 +1,46 @@
+import { Command, Types } from "../Loader.js";
+
+type GroupBuilderOptions = {
+  name: string;
+  aliases?: string[];
+  description?: string;
+  as_slash?: boolean;
+  as_prefix?: boolean;
+  guildOnly?: boolean;
+  defaultMemberPermissions?: string | bigint;
+  userPermissions?: string[];
+  botPermissions?: string[];
+  guards?: Array<(ctx: any) => boolean | Promise<boolean>>;
+};
+
+export declare class GroupBuilder {
+  name: string;
+  aliases: string[];
+  description: string;
+  commands: Command<Types.Normal>[];
+  as_slash: boolean;
+  as_prefix: boolean;
+  guildOnly: boolean | undefined;
+  defaultMemberPermissions?: string | bigint | undefined;
+  userPermissions: string[];
+  botPermissions: string[];
+  guards: Array<(ctx: any) => boolean | Promise<boolean>>;
+  constructor(ops?: GroupBuilderOptions);
+  setName(name: string): GroupBuilder;
+  setDescription(description: string): GroupBuilder;
+  addCommand(command: Command<Types.Normal>): GroupBuilder;
+  setGuards(...guards: Array<(ctx: any) => boolean | Promise<boolean>>): GroupBuilder;
+  setUserPermissions(...permissions: string[]): GroupBuilder;
+  setBotPermissions(...permissions: string[]): GroupBuilder;
+  allowPrefix(allow: boolean): GroupBuilder;
+  allowSlash(allow: boolean): GroupBuilder;
+  toJSON(): {
+    name: string;
+    description: string;
+    options: any[];
+    default_member_permissions: string | null | undefined;
+    dm_permission: boolean | undefined;
+  };
+}
+
+export {};