discord.simplified.js 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StratoX Development
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,598 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# discord.simplified.js
+
+[![npm version](https://img.shields.io/npm/v/discord.simplified.js?style=flat-square&color=cb3837&label=npm)](https://www.npmjs.com/package/discord.simplified.js)
+[![npm downloads](https://img.shields.io/npm/dm/discord.simplified.js?style=flat-square&color=4b5563&label=downloads)](https://www.npmjs.com/package/discord.simplified.js)
+[![license](https://img.shields.io/npm/l/discord.simplified.js?style=flat-square&color=3b82f6)](./LICENSE)
+[![discord.js](https://img.shields.io/badge/discord.js-v14-5865F2?style=flat-square)](https://discord.js.org)
+
+**A minimal, fast, and opinionated wrapper for [discord.js v14](https://discord.js.org) that removes boilerplate and adds powerful helpers.**
+
+> ⚠️ **Note:** This library is independently developed and maintained. It is **not** affiliated with, a copy of, or derived from any other library. This is an original project.
+
+</div>
+
+---
+
+## Installation
+
+```bash
+npm install discord.simplified.js
+```
+
+---
+
+## Quick Start
+
+```js
+// CommonJS
+const { Bot, EmbedBuilder, Button } = require("discord.simplified.js");
+
+// ESM
+import { Bot, EmbedBuilder, Button } from "discord.simplified.js";
+
+const client = new Bot({ intents: "all", owners: ["YOUR_USER_ID"] });
+client.start("YOUR_BOT_TOKEN");
+```
+
+---
+
+## Bot
+
+```js
+const client = new Bot({
+  intents: "all",
+  partials: "all",
+  owners: ["YOUR_USER_ID"],
+  prefix: "!",          // default: "!"
+  plugins: []           // optional — see Plugin System below
+});
+
+await client.start("TOKEN");
+```
+
+### Methods
+
+```js
+client.isOwner(message.author.id);                              // true/false
+const channel = await client.getChannel("CHANNEL_ID");          // cache-aware fetch
+const msg = await client.waitFor("message", m => m.author.id === "USER_ID", 15000);
+```
+
+### Event Aliases
+
+Use short clean names instead of discord.js camelCase event strings:
+
+```js
+client.on("message", msg => {});
+client.on("interaction", i => {});
+client.on("join", member => {});
+client.once("ready", () => {});
+```
+
+| Alias | Discord.js Event |
+|---|---|
+| `message` | `messageCreate` |
+| `join` | `guildMemberAdd` |
+| `leave` | `guildMemberRemove` |
+| `ban` | `guildBanAdd` |
+| `unban` | `guildBanRemove` |
+| `interaction` | `interactionCreate` |
+| `reaction` | `messageReactionAdd` |
+| `voiceUpdate` | `voiceStateUpdate` |
+| `auditLog` | `guildAuditLogEntryCreate` |
+| `guildJoin` | `guildCreate` |
+| `guildLeave` | `guildDelete` |
+| *(+ 80 more aliases)* | |
+
+---
+
+## Plugin System
+
+The plugin system lets you extend your bot with reusable, npm-publishable modules. Plugins can register slash commands, prefix commands, scheduled tasks, middleware, and hook into any Discord event.
+
+```js
+const myPlugin = require("@my-scope/my-plugin");
+const { Bot } = require("discord.simplified.js");
+
+const bot = new Bot({
+  intents: "all",
+  partials: "all",
+  plugins: [myPlugin]
+});
+
+bot.plugin.myPlugin.doSomething();
+bot.start("TOKEN");
+```
+
+### Plugin Contract
+
+```js
+module.exports = {
+  name: "example",
+
+  init(bot) {},
+  onReady() {},
+  onDestroy() {},
+
+  onMessage(msg) {},
+  onMessageEdit(oldMsg, newMsg) {},
+  onMessageDelete(msg) {},
+
+  onMemberJoin(member) {},
+  onMemberLeave(member) {},
+  onMemberUpdate(oldMember, newMember) {},
+
+  onInteraction(interaction) {},
+  onSlashCommand(interaction) {},
+  onButton(interaction) {},
+  onSelectMenu(interaction) {},
+  onModal(interaction) {},
+
+  messageMiddleware(msg) {},       // return false to block further handling
+  interactionMiddleware(interaction) {},
+
+  commands: [
+    {
+      name: "ping",
+      description: "Pings the bot",
+      options: [],
+      execute(interaction) { interaction.reply({ content: "Pong!" }); }
+    }
+  ],
+
+  prefixCommands: [
+    {
+      name: "hello",
+      aliases: ["hi", "hey"],
+      execute(msg, args) { msg.channel.send(`Hello, ${msg.author.username}!`); }
+    }
+  ],
+
+  tasks: [
+    {
+      name: "status-update",
+      interval: 60000,
+      execute(bot) { bot.user.setActivity("with plugins!"); }
+    }
+  ],
+
+  onGuildJoin(guild) {},
+  onGuildLeave(guild) {},
+  onVoiceUpdate(oldState, newState) {},
+  onRoleCreate(role) {},
+  onRoleDelete(role) {},
+  onChannelCreate(channel) {},
+  onChannelDelete(channel) {},
+  onError(error) {}
+};
+```
+
+### Plugin Isolation
+
+Every plugin runs inside a try/catch. If one plugin throws, it is logged and the rest continue — a broken plugin cannot crash your bot.
+
+---
+
+## Builders
+
+### EmbedBuilder
+
+```js
+const embed = new EmbedBuilder()
+  .title("Hello")
+  .description("This is an embed")
+  .color(Colors.blurple)
+  .field("Name", "Value", true)
+  .footer("Made with discord.simplified.js")
+  .timestamp();
+```
+
+### Button / Row / Select
+
+```js
+const button = new Button()
+  .label("Click Me")
+  .style("green")   // blue, green, red, gray, link — or ButtonStyle enum
+  .id("btn_1");
+
+const row = new Row().add(button);
+
+const select = new Select()
+  .id("menu_1")
+  .placeholder("Choose one")
+  .min(1).max(1)
+  .option("Option 1", "val_1");
+```
+
+### Modal
+
+```js
+const modal = new Modal()
+  .id("feedback_modal")
+  .title("Give Feedback")
+  .field("Your Name", "name", "short", { placeholder: "Enter your name", required: true })
+  .field("Your Message", "message", "paragraph", { placeholder: "Type here...", max: 500 });
+
+await interaction.showModal(modal);
+```
+
+---
+
+## Components V2 (CV2)
+
+For bots using the new Discord Components V2 system (`MessageFlags.V2` / `IsComponentsV2`).
+
+### ComponentBuilder
+
+Wraps `ContainerBuilder` with chainable helpers:
+
+```js
+const { ComponentBuilder, text, Flags } = require("discord.simplified.js");
+
+const container = new ComponentBuilder()
+  .addText("## Hello World")
+  .addSeparator()
+  .addButtons(button1, button2)
+  .addMedia(["https://example.com/image.png"])
+  .addSection(section)
+  .addFile(file);
+
+await channel.send({ components: [container], flags: Flags.V2 });
+```
+
+### Section
+
+A section groups text on the left with an accessory (thumbnail or button) on the right. The last `.thumbnail()` or `.button()` call wins.
+
+```js
+const { Section } = require("discord.simplified.js");
+
+// With a thumbnail accessory
+const section = new Section()
+  .text("**User Profile**\nJoined 3 months ago")
+  .thumbnail("https://example.com/avatar.png");
+
+// With a button accessory
+const section = new Section()
+  .text("Click to open settings")
+  .button("Open", "blue", "open_settings");
+```
+
+### Thumbnail
+
+A media thumbnail — only valid as a section accessory, not standalone.
+
+```js
+const { Thumbnail } = require("discord.simplified.js");
+
+const thumb = new Thumbnail()
+  .url("https://example.com/image.png")
+  .description("Alt text for accessibility");
+
+const section = new Section()
+  .text("Some content")
+  .setAccessory(thumb);
+```
+
+### FileComponent / File
+
+Attaches a file URL to a CV2 message. Exported as both `FileComponent` and `File`.
+
+```js
+const { File, ComponentBuilder, Flags } = require("discord.simplified.js");
+
+const container = new ComponentBuilder()
+  .addText("Here is your report:")
+  .addFile("attachment://report.pdf")
+  .addFile(new File().url("attachment://report.pdf"));
+
+await channel.send({ components: [container], flags: Flags.V2 });
+```
+
+---
+
+## Logger
+
+A built-in logger with timestamps, levels, and ANSI color output. No external dependencies.
+
+```js
+const { Logger, log } = require("discord.simplified.js");
+
+// Use the default instance (tag: "dislang")
+log.info("Bot started");
+log.warn("Rate limit approaching");
+log.error("Failed to fetch channel");
+log.success("Connected to gateway");
+log.debug("Raw event received");   // only shown if Logger.debug = true
+
+// Create a tagged instance
+const logger = new Logger("Music");
+logger.info("Player started");
+// → [14:23:01] [Music] [INFO] Player started
+
+// Enable debug logs globally
+Logger.debug = true;
+```
+
+Output format: `[HH:MM:SS] [TAG] [LEVEL] message`
+
+Exported as both `Logger` and `Log`.
+
+---
+
+## Presence / Status
+
+Set your bot's status and activity, or rotate through multiple presences automatically.
+
+```js
+const { Bot } = require("discord.simplified.js");
+const bot = new Bot({ intents: "all" });
+
+bot.on("ready", () => {
+  // Single presence
+  bot.setPresence({
+    status: "online",        // online | idle | dnd | invisible
+    type: "playing",         // playing | listening | watching | competing | streaming | custom
+    text: "with discord.js"
+  });
+
+  // Streaming (requires url)
+  bot.setPresence({ type: "streaming", text: "a game", url: "https://twitch.tv/someone" });
+
+  // Rotate every 15 seconds
+  bot.rotatePresence([
+    { type: "playing", text: "with slash commands" },
+    { type: "watching", text: `${guild.memberCount} members` },
+    { type: "listening", text: "your commands" }
+  ], 15000);
+
+  // Stop rotation
+  bot.stopRotation();
+});
+```
+
+Exported as both `Presence` and `Status`.
+
+---
+
+## Interaction Collectors
+
+Wait for a single component interaction or collect many.
+
+### awaitComponent
+
+Available on both `message` and `interaction`.
+
+```js
+// Wait for a button click
+const click = await msg.awaitComponent({
+  type: "button",       // button | select | modal
+  id: "confirm",        // optional: match a specific customId
+  user: interaction.user.id,  // optional: only accept from this user
+  time: 30000           // timeout in ms (default: 30000)
+});
+click.ok("Confirmed!");
+
+// From an interaction
+const click = await interaction.awaitComponent({ type: "button", id: "confirm" });
+```
+
+On timeout, rejects with: `awaitComponent timed out after 30s waiting for a button interaction`
+
+### collectComponents
+
+Collect multiple interactions over time.
+
+```js
+const collector = msg.collectComponents({
+  type: "button",
+  time: 60000,
+  max: 10,
+  onCollect: i => i.ok("You clicked: " + i.customId),
+  onEnd: collected => log.info("Done, got " + collected.size + " clicks")
+});
+
+// Stop early
+collector.stop();
+```
+
+---
+
+## Interaction Sugar
+
+Forget checking `replied` or `deferred` manually — these handle it automatically:
+
+```js
+client.on("interaction", async (i) => {
+  await i.ok("Done! ✅");                    // normal reply
+  await i.ok("Done! ✅", true);              // ephemeral
+  await i.fail("❌ Something went wrong!");   // always ephemeral
+  await i.private("Only you can see this"); // always ephemeral
+  await i.think();                          // defer (visible)
+  await i.think(true);                      // defer (ephemeral)
+  await i.refresh("Updated content");       // edit if already replied
+});
+```
+
+---
+
+## Timestamp Helper
+
+```js
+import { time } from "discord.simplified.js";
+
+time(new Date(), "relative")  // → "2 hours ago"
+time(new Date(), "short")     // → "9:41 PM"
+time(new Date(), "long")      // → "9:41:30 PM"
+time(new Date(), "date")      // → "01/01/2024"
+time(new Date(), "longdate")  // → "January 1, 2024"
+time(new Date(), "full")      // → "January 1, 2024 9:41 PM"
+time(new Date(), "longfull")  // → "Friday, January 1, 2024 9:41 PM"
+```
+
+---
+
+## Color Constants
+
+```js
+import { Colors } from "discord.simplified.js";
+
+new EmbedBuilder().color(Colors.blurple);
+new EmbedBuilder().color(Colors.red);
+
+// Available: blurple, white, black, dark, gray/grey,
+// red, green, yellow, blue, orange, purple, pink,
+// gold, teal, cyan, navy, transparent
+```
+
+---
+
+## Cooldown Manager
+
+```js
+import { Cooldown } from "discord.simplified.js";
+
+const cd = new Cooldown(5000); // 5 seconds
+
+client.on("message", (msg) => {
+  if (cd.check(msg.author.id)) {
+    return msg.reply(`⏳ Wait ${cd.remainingText(msg.author.id)}`);
+  }
+  cd.set(msg.author.id);
+  // handle command
+});
+
+cd.remaining(userId);     // → ms remaining
+cd.remainingText(userId); // → "4s" or "1m 30s"
+cd.clear(userId);         // remove one user's cooldown
+cd.reset();               // clear all cooldowns
+```
+
+---
+
+## Message Extensions
+
+```js
+message.reply("Hello!");
+message.reply({ text: "Hey!", ping: true });
+message.ping();
+message.deleteSafe();
+message.reactSafe("👍");
+message.edit("New content");
+
+message.collect({
+  from: "USER_ID",
+  time: 15000,
+  onMessage: m => console.log(m.content),
+  onEnd: collected => console.log(`Got ${collected.size} messages`)
+});
+
+const reply = await message.awaitReply(m => m.author.id === "USER_ID", 15000);
+```
+
+---
+
+## User / Member / Guild / Channel Extensions
+
+```js
+// User
+await user.dm("Hello!");
+await user.dm({ content: "Hello!", embeds: [embed] });
+
+// GuildMember
+if (member.hasRole("ROLE_ID")) {}
+if (member.can("BanMembers")) {}
+await member.addRole("ROLE_ID");
+await member.removeRole("ROLE_ID", "reason");
+await member.timeout(5, "Spamming");  // 5 minutes
+await member.timeout(null);           // remove timeout
+
+// Guild
+const member  = guild.findMember("Karan");
+const role    = guild.findRole("Moderator");
+const channel = guild.findChannel("general");
+
+// Channel
+await channel.sendEmbed(embed);
+await channel.sendEmbed([embed1, embed2]);
+await channel.sendButtons("Choose:", row1, row2);
+await channel.purge(10);
+```
+
+---
+
+## VoiceChannelStatus
+
+```js
+await VoiceChannelStatus.set("🎮 Gaming", "CHANNEL_ID");
+await VoiceChannelStatus.remove("CHANNEL_ID");
+
+// Aliases
+await VCS.set("🎧 Music", "CHANNEL_ID");
+await VCStatus.remove("CHANNEL_ID");
+```
+
+---
+
+## sendWebhook
+
+```js
+await sendWebhook("WEBHOOK_URL", "Hello!");
+await sendWebhook("WEBHOOK_URL", { content: "Hello!", username: "My Bot", embeds: [embed] });
+```
+
+---
+
+## File Structure
+
+```
+discord.simplified.js/
+  index.js      ← CommonJS  (require)
+  index.cjs     ← CommonJS  (explicit .cjs)
+  index.mjs     ← ESM       (import)
+  index.d.ts    ← TypeScript declarations
+```
+
+---
+
+## How It Works
+
+- Everything is in a **single file per format** — zero internal imports, zero path issues
+- All patches are **auto-applied** when you require/import the library
+- Plugins are **isolated in try/catch** — a broken plugin cannot crash your bot
+- Slash commands from plugins are **auto-registered globally** on ready
+- Plugin tasks are **auto-started on ready** and **auto-cleared on destroy**
+- Errors route through the built-in **Logger** with timestamps and color output
+
+---
+
+## Changelog
+
+### 2.2.0
+- Added **Logger** / `Log` / `log` — built-in timestamped ANSI logger with levels and tag support
+- Added **Presence** / `Status` — `bot.setPresence()`, `bot.rotatePresence()`, `bot.stopRotation()`
+- Added **`awaitComponent`** and **`collectComponents`** on `Message` and `BaseInteraction`
+- `_throwErr` now routes through the Logger for consistent output
+
+### 2.1.0
+- Added **Components V2** builders: `Section`, `Thumbnail`, `FileComponent` / `File`
+- Added `addSection()` and `addFile()` to `ComponentBuilder`
+- `addFile()` accepts a plain URL string or a `FileComponent` instance
+- Full TypeScript declarations for all new classes
+
+### 2.0.1
+- Added full **Plugin System** with slash commands, prefix commands, scheduled tasks, middleware, and event hooks
+- Added `prefix` option to `BotOptions`
+- Added `bot.plugin` map for accessing loaded plugin instances
+- Full TypeScript support for the plugin interface
+
+### 2.0.0
+- Initial release
+
+---
+
+## License
+
+MIT License © 2026 discord.simplified.js