@tryty/easydc-js 0.0.0-stage → 1.2.0

package/README.md

@@ -1,3 +1,913 @@
-# Temporary Holding Version
+# easydc-js
 
-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.
+A **super easy** Discord Bot wrapper built on top of [discord.js](https://discord.js.org). You only need to write commands using the `$function[argument]` syntax, without having to manually manage events, embeds, buttons, or databases.
+
+```js
+const { Bot } = require('easydc-js');
+
+const bot = new Bot({ token: process.env.TOKEN, prefix: '!' });
+
+bot.command({ name: 'ping', code: '🏓 Pong! $ping ms' });
+
+bot.connect();
+```
+
+Type `!ping` in Discord → the bot replies `🏓 Pong! 42 ms`.
+
+> **Note:** This is an independent package, not an official part of discord.js. This package uses discord.js under the hood.
+
+---
+
+## Table of Contents
+
+1. [Installation](#1-installation)
+2. [Creating a Bot on Discord](#2-creating-a-bot-on-discord)
+3. [Your First Bot](#3-your-first-bot)
+4. [How the `$function` Syntax Works](#4-how-the-function-syntax-works)
+5. [Handler Types](#5-handler-types)
+6. [Bot Options](#6-bot-options)
+7. [Variables & Database](#7-variables--database)
+8. [The `$if` Condition](#8-the-if-condition)
+9. [Embeds, Buttons, Select Menus](#9-embeds-buttons-select-menus)
+10. [Advanced Features: Modals, Autocomplete, Right-Click Menus, Polls, Threads, Webhooks](#10-advanced-features)
+11. [Eval (Owner Only)](#11-eval-owner-only)
+12. [Database & Plugins (MongoDB)](#12-database--plugins-mongodb)
+13. [Creating Custom Functions](#13-creating-custom-functions)
+14. [Splitting Commands into Multiple Files](#14-splitting-commands-into-multiple-files)
+15. [Security](#15-security)
+16. [Troubleshooting](#16-troubleshooting)
+17. [List of All Functions](#17-list of-all-functions)
+
+---
+
+## 1. Installation
+
+Requires **Node.js 18.17 or newer**.
+
+```bash
+npm install easydc-js discord.js
+```
+
+## 2. Creating a Bot on Discord
+
+1. Open <https://discord.com/developers/applications> → **New Application**.
+2. Go to the **Bot** menu → **Reset Token** → copy the token. **Do not share it with anyone.**
+3. On the same page, enable **Privileged Gateway Intents**:
+   - **Message Content Intent** (required for commands starting with prefix `!` to be read)
+   - **Server Members Intent** (for member join/leave events & member info)
+4. Go to the **OAuth2 → URL Generator** menu → check `bot` and `applications.commands` → select the required permissions → open the generated URL to invite the bot.
+
+Store the token in environment variables, do not write it directly in your code:
+
+```bash
+# Linux / macOS
+TOKEN="your_token" node index.js
+# Windows PowerShell
+$env:TOKEN="your_token"; node index.js
+```
+
+## 3. Your First Bot
+
+Create `index.js`:
+
+```js
+const { Bot } = require('easydc-js');
+
+const bot = new Bot({
+  token: process.env.TOKEN,
+  prefix: '!',
+  timezone: 'Asia/Jakarta',
+});
+
+bot.variables({ money: 100 });
+
+bot.command({
+  name: 'money',
+  code: '💰 $username has $getUserVar[money] coins',
+});
+
+bot.command({
+  name: 'work',
+  code: `
+$cooldown[1m;Take a rest first, please wait %time%.]
+$setUserVar[money;$math[$getUserVar[money]+25]]
+You got 25 coins! Total: $getUserVar[money]
+`,
+});
+
+bot.connect();
+```
+
+A complete example can be found in [`examples/basic.js`](examples/basic.js).
+
+## 4. How the `$function` Syntax Works
+
+```
+$functionName[argument1;argument2;...]
+```
+
+- Arguments are separated by a **semicolon** `;`.
+- Functions can be **nested**: `$toUpperCase[$username]`, `$math[$getUserVar[money]*2]`.
+- Function names are **case-insensitive** (`$Username` = `$username`).
+- Functions that do not require arguments are written without parentheses: `$ping`, `$serverName`.
+- The final result of the entire text (after all `$functions` are executed) is sent as the bot's reply.
+- Texts exceeding 2000 characters are automatically split into multiple messages.
+
+### Writing Special Characters
+
+To write `$ [ ] ;` characters as literal text, escape them with a backslash:
+
+| Write | Result |
+|---|---|
+| `\$ping` | `$ping` (will not be executed) |
+| `\[` `\]` | `[` `]` |
+| `\;` | `;` (will not separate arguments) |
+| `\` | `\` |
+
+Alternatively, use the functions `$semicolon`, `$leftBracket`, `$rightBracket`, `$dollar`.
+A `$` sign followed by a number or space (e.g., `price $5`) is automatically treated as plain text.
+
+> Inside JavaScript template strings (backticks `` ` ``), backslashes need to be **doubled**: `` `\$ping` ``. If you want to avoid this, use `$dollar`.
+
+### Code Validation Before Bot Starts
+
+When `bot.connect()` is called, **all code is validated first**. If there is a misspelled function, wrong number of arguments, or an `$if` without an `$endif`, the bot **will not log in** and you will get a full list of issues, for example:
+
+```
+Found 2 issues in the code:
+ - command "ban": Unknown function $bann (line 3, column 1)
+ - command "check": $if is not closed, add $endif (line 1, column 1)
+```
+
+## 5. Handler Types
+
+### Prefix Commands
+
+```js
+bot.command({ name: 'greet', aliases: ['hi', 'hello'], code: 'Hello $username!' });
+```
+
+Arguments after the command name: `$message` (all), `$message[1]` (1st word), `$argsCount`.
+
+### Slash Commands
+
+```js
+bot.slashCommand({
+  name: 'hello',                       // lowercase, no spaces
+  description: 'Greets someone',
+  options: [
+    { name: 'name', description: 'Name', type: 'string', required: true },
+    { name: 'age', description: 'Age', type: 'integer', minValue: 1 },
+  ],
+  code: 'Hello, $option[name]!',
+});
+```
+
+Option types: `string integer boolean user channel role mentionable number attachment`.
+Slash commands are automatically registered when the bot is ready. For fast testing, set `slashGuild: 'GUILD_ID'` (appears instantly; global registration can take time).
+If the process takes longer than 3 seconds, put `$defer` at the top of the code.
+
+### Buttons & Select Menus
+
+```js
+bot.command({
+  name: 'button',
+  code: '$addButton[Click;primary;click_1]$addButton[Web;link;https://example.com]Choose:',
+});
+
+bot.button({ customId: 'click_*', code: '$ephemeral You pressed `$customID`' });   // * = wildcard
+
+bot.command({
+  name: 'menu',
+  code: `Choose a fruit:
+$addSelectMenu[fruit;Choose...]
+$addSelectOption[Apple;apple;Red fruit]
+$addSelectOption[Orange;orange]`,
+});
+bot.select({ customId: 'fruit', code: 'You chose: $interactionValues' });
+```
+
+Use `$update` so that buttons/selects edit the original message instead of sending a new one.
+
+### Events
+
+| Short form | Executed when |
+|---|---|
+| `bot.onReady(code)` | bot is ready |
+| `bot.onMemberJoin(code)` | member joins the server |
+| `bot.onMemberLeave(code)` | member leaves |
+| `bot.onMessageDelete(code)` | message is deleted |
+| `bot.onMessageUpdate(code)` | message is edited |
+| `bot.onReactionAdd(code)` / `onReactionRemove` | reaction is added / removed |
+| `bot.onGuildJoin(code)` / `onGuildLeave` | bot joins / leaves a server |
+| `bot.onMessage(code)` | every message that is **not** a command |
+| `bot.onMemberBan(code)` / `onMemberUnban` | user is banned / ban lifted (`$targetID`, `$targetName`) |
+| `bot.onChannelCreate(code)` / `onChannelDelete` | channel is created / deleted (`$targetName`) |
+| `bot.onRoleCreate(code)` / `onRoleDelete` | role is created / deleted (`$targetName`) |
+| `bot.onThreadCreate(code)` | new thread (reply is sent to that thread) |
+| `bot.onVoiceJoin(code)` / `onVoiceLeave` | member joins / leaves voice (`$targetName` = voice name). Changing channels triggers both |
+
+By default, replies are sent to the system channel of the server. Choose another channel using an object format:
+
+```js
+bot.onMemberJoin({ channel: 'CHANNEL_ID', code: 'Welcome $mention! We are now $memberCount people.' });
+```
+
+## 6. Bot Options
+
+```js
+new Bot({
+  token: 'REQUIRED',
+  prefix: '!',                  // or ['!', '?']
+  mentionPrefix: true,          // @bot command works too
+  ignoreBots: true,             // ignore messages from other bots
+  owners: ['YOUR_ID'],          // for $onlyOwner and $isOwner
+  timezone: 'Asia/Jakarta',     // for $date
+  intents: 'default',           // 'default' | 'all' | ['Guilds', ...]
+  status: { text: 'with code', type: 'Playing', status: 'online' },
+  slashGuild: null,             // server ID for fast slash deployment (null = global)
+  syncSlash: true,              // auto register slash commands
+  database: { path: './easydc-data.json' },   // or { memory: true }
+  messages: { cooldown: '⏳ Wait %time%.', error: '❌ An error occurred.' },
+  debug: false,                 // true = show error causes in chat (development only!)
+  onError: (err, ctx) => {},    // handle errors manually
+});
+```
+
+Default intents: `Guilds, GuildMessages, MessageContent, GuildMembers, GuildMessageReactions, DirectMessages, GuildModeration, GuildVoiceStates`.
+
+Additional option: `eval: false` (turns on `$eval` / `$jsEval`, see [section 11](#11-eval-owner-only)).
+
+## 7. Variables & Database
+
+Variables are permanently stored in a JSON file (`easydc-data.json`). Declare them first with default values:
+
+```js
+bot.variables({ money: 0, bio: 'Not filled yet' });
+```
+
+| Function | Scope |
+|---|---|
+| `$getUserVar[name;userID?]` `$setUserVar[name;value;userID?]` `$resetUserVar` | per user |
+| `$getServerVar` `$setServerVar` `$resetServerVar` | per server |
+| `$getChannelVar` `$setChannelVar` `$resetChannelVar` | per channel |
+| `$getGlobalVar` `$setGlobalVar` `$resetGlobalVar` | one for everyone |
+
+All values are stored as **strings**. Use `$math[...]` for calculations.
+Temporary variables during a single command execution: `$let[name;value]` and `$get[name]`.
+
+- To use MongoDB, see [section 12](#12-database--plugins-mongodb).
+- The database file is written safely and automatically. If the file is corrupted, it is **backed up** (`*.corrupt-<timestamp>`) and the bot starts fresh instead of crashing.
+- For large bots (thousands of active users), consider using a real database; the built-in `Database` is suitable for small to medium bots.
+- **A single database file must only be used by one bot process.**
+
+## 8. The `$if` Condition
+
+```
+$if[condition]
+  ...
+$elseif[condition]
+  ...
+$else
+  ...
+$endif
+```
+
+Operators: `==  !=  >  <  >=  <=`, combined with `&&` (and) / `||` (or). No parentheses required.
+If both sides are numbers, they are compared numerically (`10>9` is true); otherwise, they are compared as text.
+
+```
+$if[$getUserVar[money]>=100&&$isAdmin==true]
+Rich and admin
+$elseif[$getUserVar[money]>=100]
+Rich
+$else
+Poor
+$endif
+```
+
+**Injection safe:** dynamic values like `$message` cannot be used by users to inject operators like `&&`, `||`, and similar into the condition. The user content is always treated as a plain text string.
+
+Other constraints: `$onlyIf[condition;message?]`, `$stop[message?]`, `$onlyPerms`, `$onlyAdmin`, `$onlyOwner`, `$onlyForIDs`, `$onlyInServer`, `$argsCheck`, `$cooldown`.
+
+## 9. Embeds, Buttons, Select Menus
+
+```js
+bot.command({
+  name: 'info',
+  code: `
+$title[Info $serverName]
+$description[This server has $memberCount members.]
+$color[#5865F2]
+$thumbnail[$serverIcon]
+$addField[Created;$discordTime[$serverCreatedAt;D];true]
+$addField[Ping;$ping ms;true]
+$footer[Requested by $username]
+$addTimestamp
+`,
+});
+```
+
+- The first embed is created automatically; `$newEmbed` starts the next embed (maximum 10).
+- Colors: `#RRGGBB`, names (`red green blue yellow orange purple pink white black grey blurple`), or `random`.
+- Buttons: maximum 5 per row, 5 rows per message. New rows are made automatically, or can be forced using `$newRow`.
+- Text length is validated against Discord limits, providing clear error messages if exceeded.
+
+## 10. Advanced Features
+
+### Modals (Pop-up Forms)
+
+Modals must be the **first** response to a slash command, button, or select menu interaction (do not use `$defer` beforehand; other texts in that command will be ignored).
+
+```js
+bot.slashCommand({
+  name: 'report',
+  description: 'Send a report',
+  code: `
+$addModal[report_form;Report Form]
+$addTextInput[title;Title;short;Keep it brief;true;3;50]
+$addTextInput[content;Report content;paragraph]
+`,
+});
+
+bot.modal({
+  customId: 'report_form',          // card wildcards allowed: 'report_*'
+  code: '$ephemeral Thank you! Title: $modalValue[title] | Content: $modalValue[content]',
+});
+```
+
+Maximum 5 inputs per modal. `$addTextInput[customID;label;style?;placeholder?;required?;min?;max?;initialValue?]`, styles are `short` or `paragraph`.
+
+### Autocomplete (Dynamic Choices in Slash Commands)
+
+```js
+bot.slashCommand({
+  name: 'fruit',
+  description: 'Select a fruit',
+  options: [{ name: 'name', description: 'Fruit name', autocomplete: true }],   // cannot be used together with "choices"
+  code: 'You selected $option[name]',
+});
+
+bot.autocomplete({
+  command: 'fruit',
+  option: 'name',            // leave empty for all autocomplete options in that command
+  code: `
+$if[$checkContains[apple;$toLowerCase[$focusedValue]]==true]$addChoice[Apple;apple]$endif
+$addChoice[Orange;orange]
+$addChoice[Mango;mangga]
+`,
+});
+```
+
+`$focusedValue` = the text currently typed by the user. `$addChoice[name;value?]` max 25 choices. For `integer`/`number` options, the choice value must be a number. Discord gives 3 seconds to respond, so do not use `$wait`.
+
+### Right-Click Menus (Context Menus)
+
+```js
+bot.contextMenu({ name: 'View Profile', menu: 'user', code: '$ephemeral Profile: $targetName (ID $targetID)' });
+bot.contextMenu({ name: 'Report Message', menu: 'message', code: '$ephemeral Message "$targetContent" from $targetName reported.' });
+```
+
+Appears under the *Apps* menu when a user right-clicks a user or a message. Automatically registered alongside slash commands.
+
+### User / Role / Channel Select Menus
+
+```
+$addUserSelect[select_user;Select user;1;3]
+$addRoleSelect[select_role]
+$addMentionableSelect[select_anything]
+$addChannelSelect[select_channel;Select channel;;;text,voice]
+```
+
+Register handlers via `bot.select({ customId: 'select_user', code: 'Selected: $interactionValues' })`. Values are comma-separated IDs.
+
+### Attachments, Polls, Webhooks
+
+```
+$addAttachment[https://example.com/image.png;image.png]
+$addTextFile[notes.txt;custom text file content created on the fly]
+$poll[What to eat?;24;false;Chips;Noodles;Bread]
+$sendWebhook[https://discord.com/api/webhooks/ID/TOKEN;Hello!;Bot Name;https://example.com/avatar.png]
+```
+
+Attachments only accept `http(s)` URLs or custom on-the-fly text strings (the bot does not read files from disk). `$poll[question;hours;multi;options...]` requires 2-10 options.
+
+### Threads, Forums, and Guild Management
+
+```
+$createThread[Discussion;$messageID;1440]       -> returns thread ID
+$createForumPost[FORUM_ID;Title;Content]
+$unban[ID;reason]            $isBanned[ID]          $banCount
+$createChannel[info;text;CATEGORY_ID;Topic]   $lockChannel   $unlockChannel
+$createRole[VIP;#ff0000;true]                 $createInvite[;3600;10]
+$createEvent[WatchParty;START_MS;END_MS;Voice 1;Description]
+```
+
+Management functions use **bot permissions**, so make sure to protect them with `$onlyPerms[...]` as explained in the [Security](#15-security) section. The full list is located in the [List of All Functions](#17-list-of-all-functions) section.
+
+---
+
+## 11. Eval (Owner Only)
+
+Eval executes code inputted dynamically while the bot is running, which is useful for debugging. There are two types:
+
+| Function | Code Language Executed |
+|---|---|
+| `$eval[code]` | Wrapper-version code, which uses this package's `$function` syntax |
+| `$jsEval[code]` | JavaScript / **native discord.js** |
+
+In `$jsEval`, the following variables are available: `ctx` `client` `bot` `guild` `channel` `message` `user` `member` `interaction` `discord` (discord.js module) `db` `require`. A single expression is directly returned; for multiple statements, use `return`. Supports `await`.
+
+### Easiest Way to Use
+
+```js
+const bot = new Bot({
+  token: process.env.TOKEN,
+  owners: ['YOUR_DISCORD_ID'],
+  eval: true,                // eval is DISABLED unless turned on here
+});
+
+bot.evalCommand();           // mounts the "eval" command (name can be changed: { name: 'e', aliases: ['ev'] })
+```
+
+Then in Discord:
+
+```
+!eval $math[6*7]                         -> wrapper syntax version
+!eval Hello $username from $serverName
+!eval js client.guilds.cache.size        -> native discord.js
+!eval js guild.members.cache.filter(m => m.user.bot).size
+!eval js const g = await client.guilds.fetch(guild.id);
+return g.memberCount;
+```
+
+Results are sent inside a code block (max ±1800 characters), errors are displayed as `❌ ...`, and **tokens are automatically censored** from the output.
+
+Can also be used in custom commands: `$eval[$message]` and `$jsEval[$message]`. Use `$messageFrom[2]` to get all text starting from the 2nd word (preserving spaces and newlines).
+
+### ⚠️ Security Warnings
+
+- **`$jsEval` grants FULL access** to the bot and the machine it runs on: reading files, environment variables, sending data out, and even terminating the process. Eval only runs if `eval: true` **and** the sender is listed in `owners`; otherwise, it is rejected immediately.
+- Only include **YOUR OWN** ID in `owners`. Do not grant access to anyone else, including "trusted admins".
+- If the owner's Discord account is compromised, the attacker can take over your hosting server. Enable 2FA.
+- Disable `eval` (remove `eval: true`) in production bots that do not need it.
+- Token censoring is just an accidental leaks prevention tool, not a foolproof security measure: JS code can still read tokens and send them elsewhere.
+- Nested `$eval` calls are limited to 3 levels. Infinite loops (`while(true){}`) in `$jsEval` cannot be stopped and will freeze the bot until it is restarted.
+
+---
+
+## 12. Database & Plugins (MongoDB)
+
+By default, variable data is saved in the `easydc-data.json` file. For production bots (where data shouldn't be lost when a hosting provider deletes files, or when running across multiple servers), use **MongoDB** via a plugin.
+
+### Install the MongoDB Plugin
+
+```bash
+npm install easydc-js discord.js mongodb
+```
+
+```js
+const { Bot } = require('easydc-js');
+const { mongodb } = require('easydc-js/mongodb');
+
+const bot = new Bot({ token: process.env.TOKEN, prefix: '!' });
+
+bot.use(mongodb({
+  uri: process.env.MONGO_URI,     // e.g., mongodb+srv://user:pass@cluster0.xxxx.mongodb.net
+  dbName: 'mybot',                // database name (automatically created by MongoDB)
+}));
+
+bot.variables({ money: 100 });
+bot.command({ name: 'work', code: '$incUserVar[money;25]Your money is now $getUserVar[money]' });
+
+bot.connect();
+```
+
+That's the only change required: all `$getUserVar`, `$setUserVar`, etc., will automatically use MongoDB. `bot.use(...)` must be called **before** `bot.connect()`.
+
+How to get free MongoDB: create a cluster on MongoDB Atlas (M0 tier), create a database user, whitelist your hosting IP in *Network Access*, and copy the *connection string*. Store it in the `MONGO_URI` environment variable, **do not write it in the code**.
+
+### Plugin Options
+
+| Option | Description |
+|---|---|
+| `uri` | MongoDB URI string (required). |
+| `dbName` | Database name. If empty, uses the database name from the URI, or `test`. |
+| `collection` | Collection name, defaults to `easydc`. Each variable = one document `{ _id, v, t }`. |
+| `cache` | Defaults to `true`: read data is cached in RAM for speed. **Change to `false` if multiple bot processes share the database**, otherwise data can become stale. |
+| `cacheLimit` | Maximum keys in cache (defaults to 10000). |
+| `client` | Custom `MongoClient` instance (will not be automatically closed by the bot). |
+| `clientOptions` | Additional options passed to `new MongoClient(uri, options)`. |
+
+If MongoDB cannot be reached, the bot **will not log in** and prints `Failed to connect to database: ...` (timeout is 10 seconds).
+
+### Migrating Old Data (JSON → MongoDB)
+
+A one-time script, run it in the bot's root folder before using the plugin:
+
+```js
+const { Database, copyDatabase } = require('easydc-js');
+const { MongoDatabase } = require('easydc-js/mongodb');
+
+(async () => {
+  const oldDb = new Database({ path: './easydc-data.json' });
+  const newDb = new MongoDatabase({ uri: process.env.MONGO_URI, dbName: 'mybot' });
+  await newDb.connect();
+  console.log(await copyDatabase(oldDb, newDb));     // { copied: 120, skipped: 0 }
+  await newDb.close();
+})();
+```
+
+Existing data in MongoDB will not be overwritten. Pass `{ overwrite: true }` as the third argument if you wish to overwrite it.
+
+### `$inc...Var`: Safely Incrementing Numbers
+
+The `$setUserVar[money;$math[$getUserVar[money]+10]]` pattern can **lose data** if two commands execute concurrently (both reading the old value). Instead, use:
+
+```
+$incUserVar[money;10]        $incUserVar[money;-5]       (decrease)
+$incServerVar  $incChannelVar  $incGlobalVar
+```
+
+`$incUserVar[name;amount;userID?]` executes sequentially per variable, ensuring they do not overwrite each other. This safety applies within a **single bot process**; if you run multiple bot instances on the same database, cross-process collisions can still occur.
+
+### Creating a Custom Plugin / Database Adapter
+
+A plugin is either a function or an object `{ name, install(bot, options) }`; `install` must be synchronous.
+
+```js
+bot.use({
+  name: 'hello',
+  install(bot) {
+    bot.addFunction({ name: '$hello', params: 0, run: () => 'Hello from plugin!' });
+  },
+});
+```
+
+A database adapter (for Redis, SQLite, etc.) just needs to be an object with the following methods; all of them can be `async`:
+
+| Method | Required | Description |
+|---|---|---|
+| `get(key)` | yes | Return the value (string) or `undefined` if missing. |
+| `set(key, value)` | yes | Store a string value. |
+| `delete(key)` | yes | Delete a key. |
+| `keys(prefix?)` | no | Needed for `copyDatabase`. |
+| `connect()` / `close()` | no | Called before logging into Discord / when the bot shuts down. |
+| `flush()` | no | Save pending data. |
+
+Install using `bot.setDatabase(adapter)` or `new Bot({ database: adapter })`.
+
+> **Changes from version 1.1:** `bot.getVar`, `bot.setVar`, `bot.resetVar` now return a **Promise** (use `await`). `$function` styled commands are unaffected.
+
+---
+
+## 13. Creating Custom Functions
+
+```js
+bot.addFunction({
+  name: '$greetUser',
+  params: 1,                       // exact number of arguments (or use min/max)
+  description: 'Greets someone',
+  run: (ctx, [name]) => `Welcome, ${name}! (requested by ${ctx.user.username})`,
+});
+
+bot.command({ name: 'test', code: '$greetUser[Budi]' });
+```
+
+`run` can be `async`. `ctx` contains `bot`, `client`, `guild`, `channel`, `member`, `user`, `message`, `interaction`, `args`. Throw `new Error('message')` on failure; the message will be printed to logs.
+The option `override: true` overwrites built-in functions.
+
+## 14. Splitting Commands into Multiple Files
+
+```
+project/
+├── index.js
+└── commands/
+    ├── general.js
+    └── moderation.js
+```
+
+```js
+bot.loadCommands('./commands');
+```
+
+Each file exports a single object or an array. Add a `type` for anything other than regular prefix commands (`'slash'`, `'button'`, `'select'`, `'modal'`, `'autocomplete'`, `'contextMenu'`, or an event name like `'memberJoin'`). Complete example: [`examples/advanced/lanjutan.js`](examples/advanced/lanjutan.js).
+
+```js
+module.exports = [
+  { name: 'hello', code: 'Hello $username' },
+  { type: 'slash', name: 'ping', description: 'Check ping', code: '$ping ms' },
+  { type: 'button', customId: 'ok_*', code: 'Ok!' },
+  { type: 'memberJoin', code: 'Welcome $mention' },
+];
+```
+
+## 15. Security
+
+- **Never put tokens in your code** or push them to GitHub. Use environment variables. If a token leaks, immediately *Reset Token* in the Developer Portal.
+- Action and management functions (`$ban`, `$unban`, `$kick`, `$timeout`, `$addRole`, `$clear`, `$sendDM`, `$createChannel`, `$deleteChannel`, `$deleteRole`, `$lockChannel`, `$leaveServer`, ...) run using **bot permissions**, not the sender's permissions. **Always** protect them with `$onlyPerms[...]`, `$onlyAdmin`, or `$onlyOwner` on the first line of the command.
+- Mentions sent by the bot are restricted to users only (`@everyone` and roles will not ping anyone). Modify this via the `allowedMentions` option if necessary.
+- The `$math` calculator does not use `eval`, making it safe from arbitrary code execution.
+- Leave `debug: false` in production so that detailed error messages are not revealed to users (they will still be logged to the console).
+
+## 16. Troubleshooting
+
+| Issue | Cause / Solution |
+|---|---|
+| Bot is online but does not respond to `!ping` | Enable **Message Content Intent** in the Developer Portal. |
+| `Used disallowed intents` when logging in | Enable requested intents in the Developer Portal (Server Members / Message Content), or reduce your `intents`. |
+| Member join/leave events are not working | Enable **Server Members Intent**. |
+| Slash commands do not appear | Invite the bot with the `applications.commands` scope. Use `slashGuild` for immediate updates; global commands can take time. |
+| `Unknown function $xxx` | Misspelling. If intended as plain text, write `\$xxx` (or `$dollar`). |
+| `... requires N arguments` | Semicolon `;` count mismatch. Write `\;` if the semicolon is part of the text. |
+| Variable "not declared" | Add it inside `bot.variables({ ... })` before calling `bot.connect()`. |
+| Buttons/select menus do not respond | Ensure the `customId` on the button matches the one in `bot.button({ customId })`. |
+| `Missing Permissions` in logs | The bot lacks permissions / the bot's highest role is below the target role. |
+| `Token not provided` | `process.env.TOKEN` is empty. Check how to run the bot in section 2. |
+| Interaction failed ("This interaction failed") | Process took > 3 seconds. Place `$defer` at the top of the command. |
+| Modal does not appear / "Modal must be the first response" | Do not use `$defer` or send messages before `$addModal`. Modals are only available from slash/button/select triggers, not prefix commands. |
+| Autocomplete list is empty | Options must be defined with `autocomplete: true`, and the `bot.autocomplete({ command, option })` handler must match. Process must finish in < 3 seconds. |
+| `Package "mongodb" not found` | Run `npm install mongodb` (on panel hosting: add `mongodb` to *Additional Node Packages*). |
+| `Failed to connect to database` | Check `MONGO_URI`, user & password, and whitelist your hosting IP in MongoDB Atlas (*Network Access*). Passwords with special characters (`@ : /`) must be URL-encoded. |
+| Data in MongoDB does not update / looks stale | There is more than one bot process running on the same database: set `cache: false`. |
+| `$eval ... is disabled` | Add `eval: true` and `owners: ['YOUR_ID']` inside `new Bot({...})`. |
+| Ban / voice events are not working | `GuildModeration` / `GuildVoiceStates` intents are enabled by default; if you set `intents` manually, add both. |
+
+---
+
+## 17. List of All Functions
+
+The `?` symbol means the argument is optional. This list is automatically generated from the source code (`npm run docs`).
+
+<!-- FUNCTIONS:START -->
+
+### Info (user, server, bot, message, time)
+
+| Function | Description |
+|---|---|
+| `$username[userID?]` | Username (without ID = sender) |
+| `$usertag[userID?]` | User tag |
+| `$displayName[userID?]` | Display name (server nickname / global name / username) |
+| `$nickname[userID?]` | Nickname in the server (empty -> username) |
+| `$authorID` | ID of the message author / interaction user |
+| `$userAvatar[userID?;size?]` | Avatar URL (size 16-4096) |
+| `$isBot[userID?]` | true/false: whether the user is a bot |
+| `$userCreatedAt[userID?]` | Account creation timestamp (ms) |
+| `$mentioned[number;fallbackAuthor?]` | ID of the N-th mentioned user (if 2nd arg is yes = defaults to sender if absent) |
+| `$mention[userID?]` | Mention a user, e.g., <@123> |
+| `$serverName` | Server name |
+| `$serverID` | Server ID |
+| `$serverIcon` | Server icon URL |
+| `$memberCount` | Number of server members |
+| `$ownerID` | Server owner ID |
+| `$serverCreatedAt` | Server creation timestamp (ms) |
+| `$roleCount` | Number of roles |
+| `$channelCount` | Number of channels |
+| `$channelName[channelID?]` | Channel name (without ID = current channel) |
+| `$channelID` | Current channel ID |
+| `$channelMention[channelID?]` | Mention a channel, e.g., <#123> |
+| `$roleName[roleID]` | Role name |
+| `$roleMention[roleID]` | Mention a role, e.g., <@&123> |
+| `$botID` | Bot ID |
+| `$botName` | Bot username |
+| `$ping` | Websocket ping (ms) |
+| `$uptime` | Duration the bot has been online, e.g., "1d 2h 3m 4s" |
+| `$serverCount` | Number of servers the bot is in |
+| `$message[number?]` | All arguments after the command, or the N-th argument |
+| `$argsCount` | Argument count |
+| `$messageID` | Message / interaction ID |
+| `$messageContent` | Full text content of the triggering message |
+| `$commandName` | Name of the currently running command |
+| `$option[name]` | Value of a slash command option |
+| `$customID` | customId of the pressed button/select menu |
+| `$interactionValues[number?]` | Selected values in a select menu |
+| `$reactionEmoji` | Emoji from a reaction event |
+| `$timestamp` | Current timestamp (ms) |
+| `$unix` | Current timestamp (seconds) |
+| `$date[format?;ms?]` | Date/time string. Tokens: YYYY MM DD HH mm ss. Timezone comes from bot option |
+| `$discordTime[ms?;style?]` | Discord timestamp format <t:..>. Styles: t T d D f F R |
+
+### Text, Math & Validation
+
+| Function | Description |
+|---|---|
+| `$math[expression]` | Safe evaluation. Supports + - * / % ^ ( ) sqrt abs round floor ceil min max pow pi e |
+| `$sum[a;b;...]` | Sum of all numbers |
+| `$sub[a;b]` | a - b |
+| `$multiply[a;b;...]` | Multiply all numbers |
+| `$divide[a;b]` | a / b |
+| `$modulo[a;b]` | Remainder of division a % b |
+| `$round[number;decimals?]` | Round a number |
+| `$max[a;b;...]` | Largest number |
+| `$min[a;b;...]` | Smallest number |
+| `$random[min;max]` | Random integer (inclusive) |
+| `$randomText[a;b;...]` | Randomly select one text block |
+| `$numberSeparator[number;separator?]` | 1234567 -> 1,234,567 |
+| `$toUpperCase[text]` | UPPERCASE |
+| `$toLowerCase[text]` | lowercase |
+| `$capitalize[text]` | Capitalize the first letter |
+| `$titleCase[text]` | Capitalize The First Letter Of Each Word |
+| `$trimSpace[text]` | Trim leading/trailing spaces |
+| `$length[text]` | Character count |
+| `$reverse[text]` | Reverse string order |
+| `$repeat[text;count]` | Repeat text (max 100x) |
+| `$substring[text;start;end?]` | Extract substring (0-based index) |
+| `$replaceText[text;search;replace;limit?]` | Replace text (all, or first N occurrences) |
+| `$split[text;delimiter;number]` | Get the N-th element after splitting text |
+| `$urlEncode[text]` | URL encode a string |
+| `$semicolon` | Literal character ; |
+| `$leftBracket` | Literal character [ |
+| `$rightBracket` | Literal character ] |
+| `$dollar` | Literal character $ |
+| `$isNumber[text]` | true/false: whether it's a number |
+| `$checkContains[text;search1;search2;...]` | true if text contains any of the search words |
+| `$checkCondition[condition]` | true/false. Operators: == != > < >= <= && \|\| |
+| `$hasRole[roleID;userID?]` | true/false: member has role |
+| `$hasPerms[perms1,perms2;userID?]` | true/false: member has all permissions (discord.js permission names) |
+| `$isAdmin[userID?]` | true/false: member is an administrator |
+| `$isOwner[userID?]` | true/false: user is listed in the bot's owners |
+| `$isTrue[text]` | true if text evaluates to true/yes/1/on |
+
+### Flow Control & Constraints
+
+| Function | Description |
+|---|---|
+| `$if[condition]` | Start conditional block. Close with $endif |
+| `$elseif[condition]` | Alternative condition |
+| `$else` | If all previous conditions are false |
+| `$endif` | Close $if block |
+| `$stop[message?]` | Halt execution (optionally send a message) |
+| `$onlyIf[condition;message?]` | Proceed only if the condition is true |
+| `$onlyPerms[Perms1,Perms2;message?]` | Proceed only if the sender has all permissions (e.g., BanMembers) |
+| `$onlyBotPerms[Perms1,Perms2;message?]` | Proceed only if the bot has those permissions in the server |
+| `$onlyAdmin[message?]` | Proceed only if the sender is an administrator |
+| `$onlyOwner[message?]` | Proceed only if the sender is in the owners option |
+| `$onlyForIDs[id1,id2;message?]` | Proceed only for specific user IDs |
+| `$onlyInServer[message?]` | Proceed only if used inside a server (not DMs) |
+| `$argsCheck[requirement;message?]` | Check argument count. "2" = at least 2; also supports >=1 <=3 >1 <3 =2 |
+| `$cooldown[time;message?]` | Cooldown per user per command. %time% in message = remaining time |
+| `$wait[time]` | Pause execution briefly (max 60 seconds) |
+| `$deleteCommand` | Delete the command message sent by the user after replying |
+| `$deleteIn[time]` | Delete the bot's reply after a certain time (max 24 hours) |
+| `$ephemeral` | Slash/button: make reply visible only to the user |
+| `$reply` | Reply to the triggering command message directly using inline replies |
+| `$update` | Button/select: edit original message instead of sending a new one |
+| `$typing` | Display "is typing" status |
+| `$defer` | Slash/button: defer reply (for processes > 3s). Put $ephemeral before this if needed |
+| `$let[name;value]` | Save a temporary variable (lasts only during command execution) |
+| `$get[name]` | Retrieve a temporary variable from $let |
+
+### Variables & Database
+
+| Function | Description |
+|---|---|
+| `$setUserVar[name;value;userID?]` | Save a user variable (must be declared via bot.variables) |
+| `$getUserVar[name;userID?]` | Read a user variable |
+| `$resetUserVar[name;userID?]` | Reset a user variable to its initial value |
+| `$incUserVar[name;amount;userID?]` | Increment a numeric user var (negative = decrease). Safe from race conditions. Prints nothing |
+| `$setServerVar[name;value;serverID?]` | Save a server variable (must be declared via bot.variables) |
+| `$getServerVar[name;serverID?]` | Read a server variable |
+| `$resetServerVar[name;serverID?]` | Reset a server variable to its initial value |
+| `$incServerVar[name;amount;serverID?]` | Increment a numeric server var (negative = decrease). Safe from race conditions. Prints nothing |
+| `$setChannelVar[name;value;channelID?]` | Save a channel variable (must be declared via bot.variables) |
+| `$getChannelVar[name;channelID?]` | Read a channel variable |
+| `$resetChannelVar[name;channelID?]` | Reset a channel variable to its initial value |
+| `$incChannelVar[name;amount;channelID?]` | Increment a numeric channel var (negative = decrease). Safe from race conditions. Prints nothing |
+| `$setGlobalVar[name;value]` | Save a global variable |
+| `$getGlobalVar[name]` | Read a global variable |
+| `$resetGlobalVar[name]` | Reset a global variable to its initial value |
+| `$incGlobalVar[name;amount]` | Increment a numeric global var (negative = decrease) |
+
+### Embeds
+
+| Function | Description |
+|---|---|
+| `$newEmbed` | Start a new embed block (the first one is created automatically). Max 10 |
+| `$title[text]` | Embed title (max 256) |
+| `$embedURL[url]` | URL link on the embed title |
+| `$description[text]` | Embed description body (max 4096) |
+| `$color[#hex|name|random]` | Embed color |
+| `$footer[text;iconURL?]` | Embed footer text (max 2048) |
+| `$author[name;iconURL?;url?]` | Embed author name (max 256) |
+| `$thumbnail[url]` | Embed small thumbnail image URL |
+| `$image[url]` | Embed large main image URL |
+| `$addField[name;value;inline?]` | Add a field (max 25; inline = true/false) |
+| `$addTimestamp[ms?]` | Add a timestamp to the embed (default: current time) |
+
+### Buttons & Select Menus
+
+| Function | Description |
+|---|---|
+| `$addUserSelect[customID;placeholder?;min?;max?]` | User select menu (retrieve selected items via $interactionValues) |
+| `$addRoleSelect[customID;placeholder?;min?;max?]` | Role select menu (retrieve selected items via $interactionValues) |
+| `$addMentionableSelect[customID;placeholder?;min?;max?]` | Mentionable select menu (retrieve selected items via $interactionValues) |
+| `$addChannelSelect[customID;placeholder?;min?;max?;types?]` | Channel select menu (retrieve via $interactionValues). Types: text voice category announcement stage forum, comma-separated |
+| `$newRow` | Start a new action row for buttons (automatic every 5 buttons) |
+| `$addButton[label;style;customID/URL;disabled?;emoji?]` | Add a button. Styles: primary secondary success danger link |
+| `$addSelectMenu[customID;placeholder?;min?;max?]` | Create a base string select menu (follow up with $addSelectOption) |
+| `$addSelectOption[label;value;description?;emoji?;default?]` | Add a choice to the last select menu (max 25) |
+
+### Actions & Moderation
+
+| Function | Description |
+|---|---|
+| `$sendMessage[channelID;text]` | Send a message to another channel |
+| `$sendDM[userID;text]` | Send a DM to a user |
+| `$react[emoji1;emoji2;...]` | Add reactions to the command message |
+| `$ban[userID;reason?;deleteMessageDays?]` | Ban a user (delete messages 0-7 days) |
+| `$kick[userID;reason?]` | Kick a member |
+| `$timeout[userID;duration;reason?]` | Timeout a member (max 28 days) |
+| `$untimeout[userID;reason?]` | Remove timeout from a member |
+| `$addRole[userID;roleID;reason?]` | Give a role to a member |
+| `$removeRole[userID;roleID;reason?]` | Remove a role from a member |
+| `$setNickname[userID;nickname]` | Change nickname (leave empty to reset) |
+| `$clear[amount]` | Purge last 1-100 messages (max 14 days old). Returns count of deleted messages |
+| `$slowmode[seconds]` | Set channel slowmode rate (0 = disabled, max 21600) |
+
+### Messages, Attachments, Polls, Threads & Webhooks
+
+| Function | Description |
+|---|---|
+| `$editMessage[messageID;text;channelID?]` | Edit a message belonging to the bot itself |
+| `$deleteMessage[messageID;channelID?]` | Delete a single message |
+| `$pinMessage[messageID;channelID?]` | Pin a message |
+| `$unpinMessage[messageID;channelID?]` | Unpin a message |
+| `$addReaction[messageID;emoji;channelID?]` | Add reaction to a specific message |
+| `$messageContentOf[messageID;channelID?]` | Fetch text content of a specific message |
+| `$messageAuthorOf[messageID;channelID?]` | Fetch author ID of a specific message |
+| `$addAttachment[url;name?]` | Attach a file from a http(s) URL to the response (max 10) |
+| `$addTextFile[fileName;content]` | Attach a custom text file generated on the fly (max 1 MB) |
+| `$poll[question;hours;multi;option1;option2;...]` | Create a poll (hours 1-768, multi = true/false, 2-10 options) |
+| `$sendWebhook[webhookURL;text;username?;avatarURL?]` | Send a message via a Discord Webhook URL |
+| `$createThread[name;messageID?;autoArchiveMinutes?]` | Create a thread (from a message if messageID is provided). Archive: 60/1440/4320/10080. Returns thread ID |
+| `$archiveThread[threadID?;lock?]` | Archive a thread (lock = true to also lock it) |
+| `$addThreadMember[userID;threadID?]` | Add a user to a thread |
+| `$removeThreadMember[userID;threadID?]` | Remove a user from a thread |
+| `$createForumPost[forumID;title;content]` | Create a post inside a forum channel. Returns thread ID |
+
+### Server Management (Bans, Channels, Roles, Invites, Emojis, Events, Voice)
+
+| Function | Description |
+|---|---|
+| `$unban[userID;reason?]` | Revoke a user's ban |
+| `$isBanned[userID]` | true/false: whether the user is currently banned in this server |
+| `$banCount` | Number of banned users (reads max top 1000) |
+| `$createChannel[name;type?;parentID?;topic?]` | Create a channel. Types: text voice category announcement stage forum. Returns ID |
+| `$deleteChannel[channelID;reason?]` | Delete a channel/thread (deleting the active channel makes sending the reply fail) |
+| `$setChannelName[channelID;name;reason?]` | Change channel name |
+| `$setChannelTopic[channelID;topic;reason?]` | Change channel topic |
+| `$lockChannel[channelID?;reason?]` | Lock a channel: @everyone will be unable to send messages |
+| `$unlockChannel[channelID?;reason?]` | Unlock a channel (reverts to default configurations) |
+| `$createInvite[channelID?;maxAgeSeconds?;maxUses?]` | Create an invite link. Age 0-604800 (0 = infinite), maxUses 0-100. Returns URL |
+| `$channelType[channelID?]` | Channel type string: text voice category announcement stage forum etc. |
+| `$createRole[name;color?;hoist?;mentionable?;reason?]` | Create a role. Returns ID |
+| `$deleteRole[roleID;reason?]` | Delete a role |
+| `$setRoleName[roleID;name;reason?]` | Change role name |
+| `$setRoleColor[roleID;color;reason?]` | Change role color (#hex / name / random) |
+| `$memberRoles[userID?]` | Comma-separated list of member role IDs |
+| `$createEmoji[name;url]` | Create a guild emoji from an image URL. Returns the ready-to-use emoji string |
+| `$deleteEmoji[emojiID]` | Delete a server emoji |
+| `$createEvent[name;startMs;endMs;location;description?]` | Create a scheduled guild event (external location type). Time in ms. Returns ID |
+| `$moveMember[userID;voiceChannelID]` | Move a member to another voice channel |
+| `$disconnectMember[userID]` | Disconnect a member from a voice channel |
+| `$leaveServer[serverID?]` | Force the bot to leave a server. Bot owners only |
+
+### Modals, Autocomplete & Target Scope
+
+| Function | Description |
+|---|---|
+| `$addModal[customID;title]` | Show a pop-up form (modal). Must be the first response; other texts are ignored. Build inputs using $addTextInput |
+| `$addTextInput[customID;label;style?;placeholder?;required?;min?;max?;initialValue?]` | Add an input field to a modal (max 5). Styles: short / paragraph |
+| `$modalValue[columnCustomID]` | Retrieve submitted modal input text values (used inside bot.modal handlers) |
+| `$focusedValue` | Autocomplete: text currently typed by the user |
+| `$focusedOption` | Autocomplete: name of the option currently being focused |
+| `$addChoice[name;value?]` | Autocomplete: add a dynamic choice (max 25). Default value = name |
+| `$targetID` | Target ID: right-clicked user/message, or the target entity of an event (channel/role/thread/voice/ban) |
+| `$targetName` | Target name (username / channel name / role name) |
+| `$targetContent` | Target message content (right-click message context menu) |
+| `$messageFrom[number]` | The entire message string starting from the N-th word (spaces and newlines are preserved) |
+
+### Eval (Owner Only)
+
+| Function | Description |
+|---|---|
+| `$eval[code]` | Dynamically execute wrapper-version ($function) syntax string during runtime. Requires eval: true and owner status |
+| `$jsEval[javascriptCode]` | Dynamically execute native discord.js/JavaScript code. Variables: ctx client bot guild channel message user member interaction discord db require. Requires eval: true and owner status |
+
+<!-- FUNCTIONS:START -->
+
+---
+
+## What is Not Supported Yet
+
+This package does not cover 100% of discord.js capabilities. The following features are currently missing: database adapters other than JSON and MongoDB (SQLite, Redis, etc., though you can build your own adapter, see section 12), **voice/music support** (audio streaming), **sharding**, **AutoMod rules**, **stickers**, granular channel permission overrides, and Components V2. For these features, use `bot.client` (native discord.js client) or inject custom functionalities via `bot.addFunction`.
+
+## Version History
+
+- **1.2.0**: Plugin system architecture (`bot.use`, `bot.setDatabase`), official **MongoDB** plugin support (`easydc-js/mongodb`), `copyDatabase` migration toolkit for JSON files, `$incUserVar` and relative wrapper extensions (atomic number adjustment). `bot.getVar/setVar/resetVar` are now asynchronous.
+- **1.1.0**: Added `$unban` and full guild management suites (channels, roles, invites, emojis, events, voice actions), edit/delete/pin message commands, file attachment mechanisms, poll generation, webhook triggers, threads & forums integration, modal setups, autocomplete parameters, context menus, user/role/channel dedicated selector components, 9 brand new lifecycle events, and `$eval` / `$jsEval` / `bot.evalCommand`. Default intents expanded to include `GuildModeration` and `GuildVoiceStates`.
+- **1.0.0**: Initial release.
+
+## License
+
+MIT