novaapp-sdk 1.0.9 → 1.1.0

package/dist/index.mjs

@@ -240,8 +240,9 @@ var ServersAPI = class {
 
 // src/api/interactions.ts
 var InteractionsAPI = class {
-  constructor(http) {
+  constructor(http, emitter) {
     this.http = http;
+    this.emitter = emitter;
   }
   /**
    * Acknowledge an interaction without sending a visible response.
@@ -290,6 +291,71 @@ var InteractionsAPI = class {
     const qs = params.toString();
     return this.http.get(`/interactions${qs ? `?${qs}` : ""}`);
   }
+  /**
+   * Open a modal for the user who triggered an interaction and await their submission.
+   *
+   * Internally this:
+   *  1. Calls `respond(interactionId, { modal })` to push the modal to the client UI.
+   *  2. Listens for the next `interactionCreate` event whose type is `MODAL_SUBMIT`
+   *     and whose `customId` matches your modal's `customId`.
+   *  3. Resolves with the submitted `Interaction` (containing `modalData`), or `null`
+   *     if the user closes the modal without submitting within the timeout.
+   *
+   * @param interactionId - ID of the triggering interaction.
+   * @param modal         - Modal definition (title, customId, fields).
+   * @param options.timeout - Max milliseconds to wait (default: 300 000 = 5 min).
+   *
+   * @example
+   * client.on('interactionCreate', async (interaction) => {
+   *   if (interaction.commandName === 'report') {
+   *     const submitted = await client.interactions.awaitModal(interaction.id, {
+   *       title: 'Submit a report',
+   *       customId: 'report_modal',
+   *       fields: [
+   *         { customId: 'reason', label: 'Reason', type: 'paragraph', required: true, maxLength: 500 },
+   *       ],
+   *     })
+   *
+   *     if (!submitted) {
+   *       // User dismissed the modal or timed out — nothing to do
+   *       return
+   *     }
+   *
+   *     const reason = submitted.modalData?.reason
+   *     await client.interactions.respond(submitted.id, {
+   *       content: `Report received: ${reason}`,
+   *       ephemeral: true,
+   *     })
+   *   }
+   * })
+   */
+  awaitModal(interactionId, modal, options = {}) {
+    const ms = options.timeout ?? 3e5;
+    let listener = null;
+    let timer = null;
+    const waitPromise = new Promise((resolve) => {
+      timer = setTimeout(() => {
+        if (listener) this.emitter.off("interactionCreate", listener);
+        resolve(null);
+      }, ms);
+      listener = (interaction) => {
+        if (interaction.type === "MODAL_SUBMIT" && interaction.customId === modal.customId) {
+          if (timer) clearTimeout(timer);
+          if (listener) this.emitter.off("interactionCreate", listener);
+          resolve(interaction);
+        }
+      };
+      this.emitter.on("interactionCreate", listener);
+    });
+    return this.respond(interactionId, { modal }).then(
+      () => waitPromise,
+      (err) => {
+        if (timer) clearTimeout(timer);
+        if (listener) this.emitter.off("interactionCreate", listener);
+        return Promise.reject(err);
+      }
+    );
+  }
 };
 
 // src/api/permissions.ts
@@ -336,6 +402,185 @@ var PermissionsAPI = class {
   }
 };
 
+// src/structures/NovaInteraction.ts
+var InteractionOptions = class {
+  constructor(data) {
+    this._map = /* @__PURE__ */ new Map();
+    if (data && typeof data === "object") {
+      const d = data;
+      const opts = Array.isArray(d.options) ? d.options : [];
+      for (const o of opts) {
+        if (o?.name != null) this._map.set(String(o.name), o.value);
+      }
+    }
+  }
+  /** Whether this option was supplied by the user. */
+  has(name) {
+    return this._map.has(name);
+  }
+  getString(name, required = false) {
+    const v = this._map.get(name);
+    if (required && (v == null || v === "")) throw new Error(`Required option "${name}" is missing`);
+    return v != null ? String(v) : null;
+  }
+  getInteger(name, required = false) {
+    const v = this._map.get(name);
+    if (required && v == null) throw new Error(`Required option "${name}" is missing`);
+    return v != null ? Math.trunc(Number(v)) : null;
+  }
+  getNumber(name, required = false) {
+    const v = this._map.get(name);
+    if (required && v == null) throw new Error(`Required option "${name}" is missing`);
+    return v != null ? Number(v) : null;
+  }
+  /** Returns `true` or `false`, or `null` if not supplied. */
+  getBoolean(name) {
+    const v = this._map.get(name);
+    return v != null ? Boolean(v) : null;
+  }
+  getUser(name, required = false) {
+    return this.getString(name, required);
+  }
+  getChannel(name, required = false) {
+    return this.getString(name, required);
+  }
+  getRole(name, required = false) {
+    return this.getString(name, required);
+  }
+};
+var NovaInteraction = class _NovaInteraction {
+  constructor(_raw, _api) {
+    this._raw = _raw;
+    this._api = _api;
+    this.id = _raw.id;
+    this.type = _raw.type;
+    this.commandName = _raw.commandName ?? null;
+    this.customId = _raw.customId ?? null;
+    this.userId = _raw.userId;
+    this.channelId = _raw.channelId;
+    this.serverId = _raw.serverId ?? null;
+    this.triggerMsgId = _raw.triggerMsgId ?? null;
+    this.values = _raw.values ?? [];
+    this.modalData = _raw.modalData ?? {};
+    this.createdAt = _raw.createdAt;
+    this.options = new InteractionOptions(_raw.data);
+  }
+  // ── Type guards ─────────────────────────────────────────────────────────────
+  /** `true` when triggered by a `/slash` command. */
+  isSlashCommand() {
+    return this.type === "SLASH_COMMAND";
+  }
+  /** `true` when triggered by a `!prefix` command. */
+  isPrefixCommand() {
+    return this.type === "PREFIX_COMMAND";
+  }
+  /** `true` for both slash and prefix commands. */
+  isCommand() {
+    return this.isSlashCommand() || this.isPrefixCommand();
+  }
+  /** `true` when a button component was clicked. */
+  isButton() {
+    return this.type === "BUTTON_CLICK";
+  }
+  /** `true` when a select-menu option was chosen. */
+  isSelectMenu() {
+    return this.type === "SELECT_MENU";
+  }
+  /** `true` when the user submitted a modal form. */
+  isModalSubmit() {
+    return this.type === "MODAL_SUBMIT";
+  }
+  /** `true` during autocomplete suggestion requests. */
+  isAutocomplete() {
+    return this.type === "AUTOCOMPLETE";
+  }
+  /** `true` when triggered via a context-menu command. */
+  isContextMenu() {
+    return this.type === "CONTEXT_MENU";
+  }
+  // ── Actions ─────────────────────────────────────────────────────────────────
+  /**
+   * Respond with a message.
+   * Accepts a plain string or a full options object.
+   *
+   * @example
+   * await interaction.reply('Pong! 🏓')
+   * await interaction.reply({ content: 'Done!', ephemeral: true })
+   * await interaction.reply({ embed: new EmbedBuilder().setTitle('Stats').toJSON() })
+   */
+  reply(options) {
+    return this._api.respond(this.id, typeof options === "string" ? { content: options } : options);
+  }
+  /**
+   * Respond with a message **only visible to the user** who triggered the interaction.
+   *
+   * @example
+   * await interaction.replyEphemeral('Only you can see this!')
+   */
+  replyEphemeral(options) {
+    const resolved = typeof options === "string" ? { content: options } : options;
+    return this._api.respond(this.id, { ...resolved, ephemeral: true });
+  }
+  /**
+   * Acknowledge the interaction without sending a response yet.
+   * Shows a loading indicator to the user.
+   * Follow up with `interaction.editReply()` when you're done.
+   *
+   * @example
+   * await interaction.defer()
+   * const data = await fetchSomeSlow()
+   * await interaction.editReply({ content: `Result: ${data}` })
+   */
+  defer() {
+    return this._api.ack(this.id);
+  }
+  /**
+   * Edit the previous reply (e.g. after `defer()`).
+   *
+   * @example
+   * await interaction.defer()
+   * await interaction.editReply(`Done — processed ${count} items.`)
+   */
+  editReply(options) {
+    return this._api.respond(this.id, typeof options === "string" ? { content: options } : options);
+  }
+  /**
+   * Open a **modal dialog** and return the user's submission as a new `NovaInteraction`.
+   * Returns `null` if the user closes the modal or the timeout expires (default: 5 min).
+   *
+   * **This is the recommended way to open modals.**
+   *
+   * @example
+   * const submitted = await interaction.openModal(
+   *   new ModalBuilder()
+   *     .setTitle('Submit a report')
+   *     .setCustomId('report_modal')
+   *     .addField(
+   *       new TextInputBuilder()
+   *         .setCustomId('reason')
+   *         .setLabel('Reason')
+   *         .setStyle('paragraph')
+   *         .setRequired(true)
+   *     )
+   * )
+   *
+   * if (!submitted) return // user dismissed or timed out
+   *
+   * const reason = submitted.modalData.reason
+   * await submitted.replyEphemeral(`Report received: ${reason}`)
+   */
+  async openModal(modal, options = {}) {
+    const def = "toJSON" in modal && typeof modal.toJSON === "function" ? modal.toJSON() : modal;
+    const raw = await this._api.awaitModal(this.id, def, options);
+    if (!raw) return null;
+    return new _NovaInteraction(raw, this._api);
+  }
+  /** Returns the raw interaction data from the gateway. */
+  toJSON() {
+    return { ...this._raw };
+  }
+};
+
 // src/client.ts
 var EVENT_MAP = {
   "message.created": "messageCreate",
@@ -353,6 +598,10 @@ var NovaClient = class extends EventEmitter {
     /** The authenticated bot application. Available after `ready` fires. */
     this.botUser = null;
     this.socket = null;
+    // ── Command / component routing ───────────────────────────────────────────────────
+    this._commandHandlers = /* @__PURE__ */ new Map();
+    this._buttonHandlers = /* @__PURE__ */ new Map();
+    this._selectHandlers = /* @__PURE__ */ new Map();
     if (!options.token) {
       throw new Error("[nova-bot-sdk] A bot token is required.");
     }
@@ -368,7 +617,7 @@ var NovaClient = class extends EventEmitter {
     this.commands = new CommandsAPI(this.http);
     this.members = new MembersAPI(this.http);
     this.servers = new ServersAPI(this.http);
-    this.interactions = new InteractionsAPI(this.http);
+    this.interactions = new InteractionsAPI(this.http, this);
     this.permissions = new PermissionsAPI(this.http);
     this.on("error", () => {
     });
@@ -383,6 +632,44 @@ var NovaClient = class extends EventEmitter {
       process.exit(0);
     });
   }
+  /**
+   * Register a handler for a slash or prefix command by name.
+   * Automatically routes `interactionCreate` events whose `commandName` matches.
+   *
+   * @example
+   * client.command('ping', async (interaction) => {
+   *   await interaction.reply('Pong! 🏓')
+   * })
+   */
+  command(name, handler) {
+    this._commandHandlers.set(name, handler);
+    return this;
+  }
+  /**
+   * Register a handler for a button by its `customId`.
+   *
+   * @example
+   * client.button('confirm_delete', async (interaction) => {
+   *   await interaction.replyEphemeral('Deleted.')
+   * })
+   */
+  button(customId, handler) {
+    this._buttonHandlers.set(customId, handler);
+    return this;
+  }
+  /**
+   * Register a handler for a select menu by its `customId`.
+   *
+   * @example
+   * client.selectMenu('colour_pick', async (interaction) => {
+   *   const chosen = interaction.values[0]
+   *   await interaction.reply(`You picked: ${chosen}`)
+   * })
+   */
+  selectMenu(customId, handler) {
+    this._selectHandlers.set(customId, handler);
+    return this;
+  }
   /**
    * Connect to the Nova WebSocket gateway.
    * Resolves when the `ready` event is received.
@@ -420,8 +707,19 @@ var NovaClient = class extends EventEmitter {
         this.emit("ready", this.botUser);
         resolve();
       });
-      this.socket.on("interaction:created", (interaction) => {
+      this.socket.on("interaction:created", (raw) => {
+        const interaction = new NovaInteraction(raw, this.interactions);
         this.emit("interactionCreate", interaction);
+        const run = (h) => {
+          if (h) Promise.resolve(h(interaction)).catch((e) => this.emit("error", e));
+        };
+        if (interaction.isCommand() && interaction.commandName) {
+          run(this._commandHandlers.get(interaction.commandName));
+        } else if (interaction.isButton() && interaction.customId) {
+          run(this._buttonHandlers.get(interaction.customId));
+        } else if (interaction.isSelectMenu() && interaction.customId) {
+          run(this._selectHandlers.get(interaction.customId));
+        }
       });
       this.socket.on("bot:event", (event) => {
         this.emit("event", event);
@@ -505,13 +803,428 @@ var NovaClient = class extends EventEmitter {
     return super.emit(event, ...args);
   }
 };
+
+// src/builders/EmbedBuilder.ts
+var EmbedBuilder = class {
+  constructor() {
+    this._data = {};
+  }
+  /** Set the embed title (shown in bold at the top). */
+  setTitle(title) {
+    this._data.title = title;
+    return this;
+  }
+  /** Set the main description text (supports markdown). */
+  setDescription(description) {
+    this._data.description = description;
+    return this;
+  }
+  /**
+   * Set the accent colour.
+   * @param color Hex string — e.g. `'#5865F2'` or `'5865F2'`
+   */
+  setColor(color) {
+    this._data.color = color.startsWith("#") ? color : `#${color}`;
+    return this;
+  }
+  /** Make the title a clickable hyperlink. */
+  setUrl(url) {
+    this._data.url = url;
+    return this;
+  }
+  /** Small image shown in the top-right corner. */
+  setThumbnail(url) {
+    this._data.thumbnail = url;
+    return this;
+  }
+  /** Large image shown below the fields. */
+  setImage(url) {
+    this._data.image = url;
+    return this;
+  }
+  /** Footer text shown at the very bottom of the embed. */
+  setFooter(text) {
+    this._data.footer = text;
+    return this;
+  }
+  /**
+   * Add a timestamp to the footer line.
+   * @param date Defaults to `new Date()`.
+   */
+  setTimestamp(date) {
+    const d = date instanceof Date ? date : date != null ? new Date(date) : /* @__PURE__ */ new Date();
+    this._data.timestamp = d.toISOString();
+    return this;
+  }
+  /** Author name + optional icon shown above the title. */
+  setAuthor(author) {
+    this._data.author = author;
+    return this;
+  }
+  /**
+   * Add a single field.
+   * @param inline Pass `true` to render this field side-by-side with adjacent inline fields.
+   */
+  addField(name, value, inline) {
+    if (!this._data.fields) this._data.fields = [];
+    this._data.fields.push({ name, value, inline });
+    return this;
+  }
+  /** Add multiple fields at once. */
+  addFields(...fields) {
+    if (!this._data.fields) this._data.fields = [];
+    this._data.fields.push(...fields);
+    return this;
+  }
+  /** Replace all fields. */
+  setFields(fields) {
+    this._data.fields = [...fields];
+    return this;
+  }
+  /** Serialise to a plain `Embed` object you can pass to any API call. */
+  toJSON() {
+    return {
+      ...this._data,
+      fields: this._data.fields ? [...this._data.fields] : void 0
+    };
+  }
+};
+
+// src/builders/ButtonBuilder.ts
+var ButtonBuilder = class {
+  constructor() {
+    this._customId = "";
+    this._label = "";
+    this._style = "primary";
+    this._disabled = false;
+  }
+  /** Custom ID returned in the `BUTTON_CLICK` interaction. Not required for `link` style buttons. */
+  setCustomId(customId) {
+    this._customId = customId;
+    return this;
+  }
+  /** Text displayed on the button. */
+  setLabel(label) {
+    this._label = label;
+    return this;
+  }
+  /**
+   * Visual style:
+   * - `primary` — blurple / brand colour
+   * - `secondary` — grey
+   * - `success` — green
+   * - `danger` — red
+   * - `link` — grey, navigates to a URL instead of creating an interaction
+   */
+  setStyle(style) {
+    this._style = style;
+    return this;
+  }
+  /** Emoji shown to the left of the label (unicode or custom e.g. `'👋'`). */
+  setEmoji(emoji) {
+    this._emoji = emoji;
+    return this;
+  }
+  /**
+   * URL for `link` style buttons.
+   * Sets the style to `'link'` automatically.
+   */
+  setUrl(url) {
+    this._url = url;
+    this._style = "link";
+    return this;
+  }
+  /** Prevent users from clicking the button. */
+  setDisabled(disabled = true) {
+    this._disabled = disabled;
+    return this;
+  }
+  toJSON() {
+    return {
+      type: "button",
+      customId: this._customId,
+      label: this._label || void 0,
+      style: this._style,
+      emoji: this._emoji,
+      url: this._url,
+      disabled: this._disabled || void 0
+    };
+  }
+};
+
+// src/builders/SelectMenuBuilder.ts
+var SelectMenuBuilder = class {
+  constructor() {
+    this._customId = "";
+    this._disabled = false;
+    this._options = [];
+  }
+  /** Custom ID returned in the `SELECT_MENU` interaction. */
+  setCustomId(customId) {
+    this._customId = customId;
+    return this;
+  }
+  /** Greyed-out hint shown when nothing is selected. */
+  setPlaceholder(placeholder) {
+    this._placeholder = placeholder;
+    return this;
+  }
+  /** Prevent users from interacting with the menu. */
+  setDisabled(disabled = true) {
+    this._disabled = disabled;
+    return this;
+  }
+  /** Add a single option. */
+  addOption(option) {
+    this._options.push(option);
+    return this;
+  }
+  /** Add multiple options at once. */
+  addOptions(...options) {
+    this._options.push(...options);
+    return this;
+  }
+  /** Replace all options. */
+  setOptions(options) {
+    this._options.splice(0, this._options.length, ...options);
+    return this;
+  }
+  toJSON() {
+    return {
+      type: "select",
+      customId: this._customId,
+      placeholder: this._placeholder,
+      disabled: this._disabled || void 0,
+      options: [...this._options]
+    };
+  }
+};
+
+// src/builders/ActionRowBuilder.ts
+var ActionRowBuilder = class {
+  constructor() {
+    this._components = [];
+  }
+  /** Add a single component (button or select menu). */
+  addComponent(component) {
+    this._components.push(component);
+    return this;
+  }
+  /** Add multiple components at once. */
+  addComponents(...components) {
+    this._components.push(...components);
+    return this;
+  }
+  /**
+   * Serialise to a flat `MessageComponent[]` array — the format accepted by all API calls.
+   */
+  toJSON() {
+    return this._components.map((c) => c.toJSON());
+  }
+};
+
+// src/builders/ModalBuilder.ts
+var ModalBuilder = class {
+  constructor() {
+    this._title = "";
+    this._customId = "";
+    this._fields = [];
+  }
+  /** Title shown at the top of the modal dialog. */
+  setTitle(title) {
+    this._title = title;
+    return this;
+  }
+  /** Custom ID passed back with the `MODAL_SUBMIT` interaction. */
+  setCustomId(customId) {
+    this._customId = customId;
+    return this;
+  }
+  /** Add a single text-input field. */
+  addField(field) {
+    this._fields.push("toJSON" in field ? field.toJSON() : field);
+    return this;
+  }
+  /** Add multiple fields at once. */
+  addFields(...fields) {
+    for (const f of fields) this.addField(f);
+    return this;
+  }
+  toJSON() {
+    if (!this._title) throw new Error("ModalBuilder: title is required \u2014 call .setTitle()");
+    if (!this._customId) throw new Error("ModalBuilder: customId is required \u2014 call .setCustomId()");
+    if (this._fields.length === 0) throw new Error("ModalBuilder: at least one field is required \u2014 call .addField()");
+    return { title: this._title, customId: this._customId, fields: [...this._fields] };
+  }
+};
+
+// src/builders/TextInputBuilder.ts
+var TextInputBuilder = class {
+  constructor() {
+    this._data = {
+      customId: "",
+      label: "",
+      type: "short"
+    };
+  }
+  /** Unique ID for this field — the key in `interaction.modalData` on submit. */
+  setCustomId(customId) {
+    this._data.customId = customId;
+    return this;
+  }
+  /** Label shown above the input inside the modal. */
+  setLabel(label) {
+    this._data.label = label;
+    return this;
+  }
+  /**
+   * Input style:
+   * - `'short'` — single-line text input
+   * - `'paragraph'` — multi-line textarea
+   */
+  setStyle(style) {
+    this._data.type = style;
+    return this;
+  }
+  /** Greyed-out hint text shown when the field is empty. */
+  setPlaceholder(placeholder) {
+    this._data.placeholder = placeholder;
+    return this;
+  }
+  /** Whether the user must fill in this field before submitting. */
+  setRequired(required = true) {
+    this._data.required = required;
+    return this;
+  }
+  /** Minimum number of characters required. */
+  setMinLength(min) {
+    this._data.minLength = min;
+    return this;
+  }
+  /** Maximum number of characters allowed. */
+  setMaxLength(max) {
+    this._data.maxLength = max;
+    return this;
+  }
+  /** Pre-filled default value. */
+  setValue(value) {
+    this._data.value = value;
+    return this;
+  }
+  toJSON() {
+    return { ...this._data };
+  }
+};
+
+// src/builders/SlashCommandBuilder.ts
+var SlashCommandOptionBuilder = class {
+  constructor(type) {
+    this._data = { name: "", description: "", type };
+  }
+  /** Internal option name (lowercase, no spaces). Shown after `/command ` in the client UI. */
+  setName(name) {
+    this._data.name = name;
+    return this;
+  }
+  /** Short human-readable description shown in the command picker. */
+  setDescription(description) {
+    this._data.description = description;
+    return this;
+  }
+  /** Whether users must supply this option before sending the command. */
+  setRequired(required = true) {
+    this._data.required = required;
+    return this;
+  }
+  /**
+   * Restrict the option to specific values.
+   * The picker will show these as autocomplete suggestions.
+   */
+  addChoice(name, value) {
+    if (!this._data.choices) this._data.choices = [];
+    this._data.choices.push({ name, value });
+    return this;
+  }
+  /** Set all allowed choices at once. */
+  setChoices(choices) {
+    this._data.choices = [...choices];
+    return this;
+  }
+  toJSON() {
+    return { ...this._data };
+  }
+};
+var SlashCommandBuilder = class {
+  constructor() {
+    this._data = {
+      name: "",
+      description: "",
+      options: []
+    };
+  }
+  /** Command name — lowercase, no spaces (e.g. `'ban'`, `'server-info'`). */
+  setName(name) {
+    this._data.name = name;
+    return this;
+  }
+  /** Short description shown in the command picker UI. */
+  setDescription(description) {
+    this._data.description = description;
+    return this;
+  }
+  /** Add a text (string) option. */
+  addStringOption(fn) {
+    this._data.options.push(fn(new SlashCommandOptionBuilder("STRING")).toJSON());
+    return this;
+  }
+  /** Add an integer (whole number) option. */
+  addIntegerOption(fn) {
+    this._data.options.push(fn(new SlashCommandOptionBuilder("INTEGER")).toJSON());
+    return this;
+  }
+  /** Add a boolean (true/false) option. */
+  addBooleanOption(fn) {
+    this._data.options.push(fn(new SlashCommandOptionBuilder("BOOLEAN")).toJSON());
+    return this;
+  }
+  /** Add a user-mention option (returns a user ID string). */
+  addUserOption(fn) {
+    this._data.options.push(fn(new SlashCommandOptionBuilder("USER")).toJSON());
+    return this;
+  }
+  /** Add a channel-mention option (returns a channel ID string). */
+  addChannelOption(fn) {
+    this._data.options.push(fn(new SlashCommandOptionBuilder("CHANNEL")).toJSON());
+    return this;
+  }
+  /** Add a role-mention option (returns a role ID string). */
+  addRoleOption(fn) {
+    this._data.options.push(fn(new SlashCommandOptionBuilder("ROLE")).toJSON());
+    return this;
+  }
+  toJSON() {
+    if (!this._data.name) throw new Error("SlashCommandBuilder: name is required \u2014 call .setName()");
+    if (!this._data.description) throw new Error("SlashCommandBuilder: description is required \u2014 call .setDescription()");
+    return { ...this._data, options: [...this._data.options ?? []] };
+  }
+};
 export {
+  ActionRowBuilder,
+  ButtonBuilder,
   CommandsAPI,
+  EmbedBuilder,
   HttpClient,
+  InteractionOptions,
   InteractionsAPI,
   MembersAPI,
   MessagesAPI,
+  ModalBuilder,
   NovaClient,
+  NovaInteraction,
   PermissionsAPI,
-  ServersAPI
+  SelectMenuBuilder,
+  ServersAPI,
+  SlashCommandBuilder,
+  SlashCommandOptionBuilder,
+  TextInputBuilder
 };