@tryty/easydc-js 1.1.0 → 1.2.2

package/README.md

@@ -1,9 +1,9 @@
-# easydc-js
+# @tryty/easydc-js
 
 Bot Discord **super mudah** di atas [discord.js](https://discord.js.org). Kamu cukup menulis perintah dengan sintaks `$fungsi[argumen]` seperti aoi.js, tanpa harus mengurus event, embed, tombol, atau database secara manual.
 
 ```js
-const { Bot } = require('easydc-js');
+const { Bot } = require('@tryty/easydc-js');
 
 const bot = new Bot({ token: process.env.TOKEN, prefix: '!' });
 
@@ -21,6 +21,7 @@ Ketik `!ping` di Discord → bot menjawab `🏓 Pong! 42 ms`.
 ## Daftar isi
 
 1. [Instalasi](#1-instalasi)
+   - [Tanpa publish ke npm (file lokal)](#1b-memakai-tanpa-publish-ke-npm-file-lokal--host-panel)
 2. [Membuat bot di Discord](#2-membuat-bot-di-discord)
 3. [Bot pertama](#3-bot-pertama)
 4. [Cara kerja sintaks `$fungsi`](#4-cara-kerja-sintaks-fungsi)
@@ -31,11 +32,12 @@ Ketik `!ping` di Discord → bot menjawab `🏓 Pong! 42 ms`.
 9. [Embed, tombol, select menu](#9-embed-tombol-select-menu)
 10. [Fitur lanjutan: modal, autocomplete, menu klik-kanan, poll, thread, webhook](#10-fitur-lanjutan)
 11. [Eval (khusus owner)](#11-eval-khusus-owner)
-12. [Membuat fungsi sendiri](#12-membuat-fungsi-sendiri)
-13. [Memisah command ke banyak file](#13-memisah-command-ke-banyak-file)
-14. [Keamanan](#14-keamanan)
-15. [Pemecahan masalah](#15-pemecahan-masalah)
-16. [Daftar semua fungsi](#16-daftar-semua-fungsi)
+12. [Database & plugin (MongoDB)](#12-database--plugin-mongodb)
+13. [Membuat fungsi sendiri](#13-membuat-fungsi-sendiri)
+14. [Memisah command ke banyak file](#14-memisah-command-ke-banyak-file)
+15. [Keamanan](#15-keamanan)
+16. [Pemecahan masalah](#16-pemecahan-masalah)
+17. [Daftar semua fungsi](#17-daftar-semua-fungsi)
 
 ---
 
@@ -44,9 +46,40 @@ Ketik `!ping` di Discord → bot menjawab `🏓 Pong! 42 ms`.
 Butuh **Node.js 18.17 atau lebih baru**.
 
 ```bash
-npm install easydc-js discord.js
+npm install @tryty/easydc-js discord.js
 ```
 
+## 1b. Memakai tanpa publish ke npm (file lokal / host panel)
+
+Kalau package ini belum dipublish tetapi kode Anda sudah memakai `require('@tryty/easydc-js')`, pasang dari file lokal. Ada dua cara.
+
+**Cara A: dependensi `file:` (disarankan, tahan restart panel)**
+
+1. Ekstrak zip, lalu letakkan folder package di dalam proyek bot, misalnya `bot/vendor/easydc-js/` (isinya `src`, `package.json`, dst.).
+2. Di `package.json` **proyek bot** (bukan package-nya), tambahkan:
+   ```json
+   {
+     "dependencies": {
+       "@tryty/easydc-js": "file:./vendor/easydc-js",
+       "discord.js": "^14.16.0",
+       "mongodb": "^6.0.0"
+     }
+   }
+   ```
+3. Jalankan `npm install`. Sekarang `require('@tryty/easydc-js')` dan `require('@tryty/easydc-js/mongodb')` berfungsi persis seperti setelah publish.
+
+**Cara B: dari file `.tgz`**
+
+```bash
+npm install ./tryty-easydc-js-1.3.0.tgz discord.js mongodb
+```
+
+Jangan hanya menyalin folder ke `node_modules/@tryty/easydc-js` dengan tangan: panel yang menjalankan `npm install` saat start akan menghapus folder yang tidak tercatat di `package.json`.
+
+Nama di `require` harus sama persis dengan nama di `dependencies`. Jika Anda tidak memakai nama ber-scope, ganti `"name"` di `package.json` package-nya dan semua `require`.
+
+---
+
 ## 2. Membuat bot di Discord
 
 1. Buka <https://discord.com/developers/applications> → **New Application**.
@@ -70,7 +103,7 @@ $env:TOKEN="token_kamu"; node index.js
 Buat `index.js`:
 
 ```js
-const { Bot } = require('easydc-js');
+const { Bot } = require('@tryty/easydc-js');
 
 const bot = new Bot({
   token: process.env.TOKEN,
@@ -255,6 +288,7 @@ bot.variables({ uang: 0, bio: 'Belum diisi' });
 Semua nilai tersimpan sebagai **teks**. Gunakan `$math[...]` untuk berhitung.
 Variabel sementara selama satu command: `$let[nama;nilai]` dan `$get[nama]`.
 
+- Untuk memakai MongoDB lihat [bagian 12](#12-database--plugin-mongodb).
 - Berkas database ditulis secara aman dan otomatis. Jika file rusak, ia **dicadangkan** (`*.corrupt-<waktu>`) dan bot mulai dari kosong, bukan crash.
 - Untuk bot besar (ribuan user aktif) pertimbangkan database sungguhan; `Database` bawaan cocok untuk bot kecil sampai menengah.
 - **Satu file database hanya boleh dipakai satu proses bot.**
@@ -401,7 +435,7 @@ $createRole[VIP;#ff0000;true]                 $createInvite[;3600;10]
 $createEvent[Nobar;MULAI_MS;SELESAI_MS;Voice 1;Deskripsi]
 ```
 
-Fungsi manajemen memakai **izin bot**, jadi lindungi dengan `$onlyPerms[...]` seperti di bagian [Keamanan](#14-keamanan). Daftar lengkapnya ada di bagian [Daftar semua fungsi](#16-daftar-semua-fungsi).
+Fungsi manajemen memakai **izin bot**, jadi lindungi dengan `$onlyPerms[...]` seperti di bagian [Keamanan](#15-keamanan). Daftar lengkapnya ada di bagian [Daftar semua fungsi](#17-daftar-semua-fungsi).
 
 ---
 
@@ -443,6 +477,29 @@ Hasil dikirim dalam blok kode (maksimal ±1800 karakter), error ditampilkan seba
 
 Bisa juga dipakai di command buatan sendiri: `$eval[$message]` dan `$jsEval[$message]`. Gunakan `$messageFrom[2]` untuk mengambil semua teks mulai kata ke-2 (spasi dan baris baru terjaga).
 
+### Tes semua fitur dengan satu command (selftest)
+
+Setelah bot online di server Anda, jalankan tes otomatis langsung di Discord asli. Ini cara tercepat untuk tahu apakah semuanya benar-benar jalan di bot Anda (bukan hanya di tes tiruan):
+
+```js
+const bot = new Bot({ token: process.env.TOKEN, owners: ['ID_KAMU'] });
+bot.selfTestCommand();            // atau bot.selfTestCommand({ ui: true })
+bot.connect();
+```
+
+| Ketik | Yang diuji |
+|---|---|
+| `!selftest` | Fungsi dasar (`$math`, `$if`, `$date`, dll.), **database** (simpan, baca, tambah, reset), dan **pengiriman** embed + tombol + select menu + select user, lampiran file, dan polling. Pesan uji lampiran dan polling dihapus otomatis. |
+| `!selftest full` | Semua di atas, ditambah membuat lalu **menghapus** channel dan role sementara (nama, topik, kunci channel, undangan, edit/pin/reaksi pesan, thread). Channel/role sementara selalu dihapus walaupun ada langkah yang gagal. |
+
+Hasilnya berupa daftar `✅` (lulus), `❌` (gagal, lengkap dengan pesan penyebabnya), dan `⚠️` (dilewati karena bot kurang izin). Kirim isi daftar `❌` ke pengembang untuk diperbaiki.
+
+Yang tidak bisa diuji otomatis karena butuh klik manusia: tombol, modal, dan select menu pada pesan uji. Klik sendiri, masing-masing akan membalas `✅ ... berfungsi`. Dengan `ui: true` Anda juga mendapat `/tesauto` (ketik di opsi `buah` untuk melihat autocomplete) dan dua menu klik-kanan **Tes Profil** (klik kanan user) dan **Tes Pesan** (klik kanan pesan).
+
+Command ini khusus owner dan punya jeda 10 detik. Hapus `bot.selfTestCommand()` bila sudah tidak diperlukan, terutama `ui: true` yang meninggalkan slash command dan menu klik-kanan di server.
+
+Untuk menguji **kode package itu sendiri** (tanpa Discord) pakai `npm test` di folder package.
+
 ### ⚠️ Peringatan keamanan
 
 - **`$jsEval` memberi akses PENUH** ke bot dan mesin tempat bot berjalan: membaca file, variabel lingkungan, mengirim data keluar, bahkan mematikan proses. Eval hanya berjalan bila `eval: true` **dan** pengirim ada di `owners`; selain itu langsung ditolak.
@@ -454,7 +511,112 @@ Bisa juga dipakai di command buatan sendiri: `$eval[$message]` dan `$jsEval[$mes
 
 ---
 
-## 12. Membuat fungsi sendiri
+## 12. Database & plugin (MongoDB)
+
+Secara bawaan data variabel disimpan di file `easydc-data.json`. Untuk bot yang lebih serius (data tidak hilang saat hosting menghapus file, atau lebih dari satu server), pakai **MongoDB** lewat plugin.
+
+### Pasang plugin MongoDB
+
+```bash
+npm install @tryty/easydc-js discord.js mongodb
+```
+
+```js
+const { Bot } = require('@tryty/easydc-js');
+const { mongodb } = require('@tryty/easydc-js/mongodb');
+
+const bot = new Bot({ token: process.env.TOKEN, prefix: '!' });
+
+bot.use(mongodb({
+  uri: process.env.MONGO_URI,     // mis. mongodb+srv://user:sandi@cluster0.xxxx.mongodb.net
+  dbName: 'botku',                // nama database (dibuat otomatis oleh MongoDB)
+}));
+
+bot.variables({ uang: 100 });
+bot.command({ name: 'kerja', code: '$incUserVar[uang;25]Uangmu sekarang $getUserVar[uang]' });
+
+bot.connect();
+```
+
+Hanya itu yang berubah: semua `$getUserVar`, `$setUserVar`, dll. otomatis memakai MongoDB. `bot.use(...)` harus dipanggil **sebelum** `bot.connect()`.
+
+Cara mendapatkan MongoDB gratis: buat cluster di MongoDB Atlas (paket M0), buat user database, izinkan IP hosting Anda di *Network Access*, lalu salin *connection string*. Simpan di variabel lingkungan `MONGO_URI`, **jangan ditulis di kode**.
+
+### Opsi plugin
+
+| Opsi | Keterangan |
+|---|---|
+| `uri` | Alamat MongoDB (wajib). |
+| `dbName` | Nama database. Jika kosong dipakai nama dari URI, atau `test`. |
+| `collection` | Nama collection, bawaan `easydc`. Tiap variabel = satu dokumen `{ _id, v, t }`. |
+| `cache` | Bawaan `true`: data yang sudah dibaca disimpan di RAM supaya cepat. **Ubah ke `false` jika lebih dari satu proses bot memakai database yang sama**, kalau tidak data bisa basi. |
+| `cacheLimit` | Maksimal kunci di cache (bawaan 10000). |
+| `client` | `MongoClient` buatan sendiri (tidak ditutup otomatis oleh bot). |
+| `clientOptions` | Opsi tambahan untuk `new MongoClient(uri, opsi)`. |
+
+Jika MongoDB tidak bisa dihubungi, bot **tidak login** dan menampilkan pesan `Gagal terhubung ke database: ...` (batas tunggu 10 detik).
+
+### Memindahkan data lama (JSON → MongoDB)
+
+Skrip sekali jalan, jalankan di folder bot sebelum memakai plugin:
+
+```js
+const { Database, copyDatabase } = require('@tryty/easydc-js');
+const { MongoDatabase } = require('@tryty/easydc-js/mongodb');
+
+(async () => {
+  const lama = new Database({ path: './easydc-data.json' });
+  const baru = new MongoDatabase({ uri: process.env.MONGO_URI, dbName: 'botku' });
+  await baru.connect();
+  console.log(await copyDatabase(lama, baru));     // { copied: 120, skipped: 0 }
+  await baru.close();
+})();
+```
+
+Data yang sudah ada di MongoDB tidak ditimpa. Tambahkan `{ overwrite: true }` sebagai argumen ketiga bila ingin menimpa.
+
+### `$inc...Var`: tambah angka dengan aman
+
+Pola `$setUserVar[uang;$math[$getUserVar[uang]+10]]` bisa **kehilangan data** jika dua command berjalan bersamaan (keduanya membaca nilai lama). Gunakan:
+
+```
+$incUserVar[uang;10]        $incUserVar[uang;-5]       (kurangi)
+$incServerVar  $incChannelVar  $incGlobalVar
+```
+
+`$incUserVar[nama;jumlah;userID?]` berjalan berurutan per variabel sehingga tidak saling menimpa. Perlindungan ini berlaku di dalam **satu proses bot**; jika Anda menjalankan beberapa proses bot pada database yang sama, tabrakan antar proses masih mungkin.
+
+### Membuat plugin / adapter database sendiri
+
+Plugin adalah function atau object `{ name, install(bot, opsi) }`; `install` harus sinkron.
+
+```js
+bot.use({
+  name: 'halo',
+  install(bot) {
+    bot.addFunction({ name: '$halo', params: 0, run: () => 'Halo dari plugin!' });
+  },
+});
+```
+
+Adapter database (untuk Redis, SQLite, dll.) cukup berupa object dengan method berikut; semuanya boleh `async`:
+
+| Method | Wajib | Keterangan |
+|---|---|---|
+| `get(key)` | ya | Kembalikan nilai (teks) atau `undefined` jika tidak ada. |
+| `set(key, value)` | ya | Simpan nilai teks. |
+| `delete(key)` | ya | Hapus kunci. |
+| `keys(prefix?)` | tidak | Dibutuhkan oleh `copyDatabase`. |
+| `connect()` / `close()` | tidak | Dipanggil sebelum login Discord / saat bot dimatikan. |
+| `flush()` | tidak | Simpan data yang tertunda. |
+
+Pasang dengan `bot.setDatabase(adapter)` atau `new Bot({ database: adapter })`.
+
+> **Perubahan dari versi 1.1:** `bot.getVar`, `bot.setVar`, `bot.resetVar` kini mengembalikan **Promise** (pakai `await`). Command bergaya `$fungsi` tidak terpengaruh.
+
+---
+
+## 13. Membuat fungsi sendiri
 
 ```js
 bot.addFunction({
@@ -470,7 +632,7 @@ bot.command({ name: 'tes', code: '$salam[Budi]' });
 `run` boleh `async`. `ctx` berisi `bot`, `client`, `guild`, `channel`, `member`, `user`, `message`, `interaction`, `args`. Lempar `new Error('pesan')` bila gagal; pesan itu akan dicatat di log.
 Opsi `override: true` mengganti fungsi bawaan.
 
-## 13. Memisah command ke banyak file
+## 14. Memisah command ke banyak file
 
 ```
 proyek/
@@ -495,7 +657,7 @@ module.exports = [
 ];
 ```
 
-## 14. Keamanan
+## 15. Keamanan
 
 - **Jangan taruh token di kode** atau di GitHub. Pakai variabel lingkungan. Jika token bocor, segera *Reset Token* di Developer Portal.
 - Fungsi aksi dan manajemen (`$ban`, `$unban`, `$kick`, `$timeout`, `$addRole`, `$clear`, `$sendDM`, `$createChannel`, `$deleteChannel`, `$deleteRole`, `$lockChannel`, `$leaveServer`, ...) memakai **izin bot**, bukan izin pengirim. **Selalu** lindungi dengan `$onlyPerms[...]`, `$onlyAdmin`, atau `$onlyOwner` di baris pertama command.
@@ -503,7 +665,7 @@ module.exports = [
 - Kalkulator `$math` tidak memakai `eval`, jadi aman dari eksekusi kode.
 - Biarkan `debug: false` di produksi supaya detail error tidak tampil ke pengguna (tetap tercatat di konsol).
 
-## 15. Pemecahan masalah
+## 16. Pemecahan masalah
 
 | Masalah | Penyebab / solusi |
 |---|---|
@@ -520,12 +682,16 @@ module.exports = [
 | Interaksi gagal ("This interaction failed") | Proses > 3 detik. Taruh `$defer` di awal. |
 | Modal tidak muncul / "Modal harus jadi respons pertama" | Jangan pakai `$defer` atau kirim pesan sebelum `$addModal`. Modal hanya dari slash/tombol/select, bukan command prefix. |
 | Autocomplete kosong | Opsi harus dibuat dengan `autocomplete: true`, dan handler `bot.autocomplete({ command, option })` cocok. Proses harus selesai < 3 detik. |
+| `Package "mongodb" tidak ditemukan` | Jalankan `npm install mongodb` (di host panel: tambahkan `mongodb` ke *Additional Node Packages*). |
+| `Gagal terhubung ke database` | Periksa `MONGO_URI`, user & sandi, dan izinkan IP hosting di MongoDB Atlas (*Network Access*). Sandi dengan karakter khusus (`@ : /`) harus di-URL-encode. |
+| Data di MongoDB tidak berubah / terlihat basi | Ada lebih dari satu proses bot pada database yang sama: set `cache: false`. |
+| "Hanya untuk owner" padahal sudah isi ID | (1) ID **wajib pakai tanda kutip**: `owners: ['123456789012345678']`; tanpa kutip angkanya membulat dan tidak cocok (versi 1.2.3+ langsung memberi error). (2) Salin **User ID** akunmu (Developer Mode → klik kanan profil → Copy User ID), bukan ID server/bot. (3) Lihat konsol panel: tertulis `[easydc] ... ID pengirim = "..."`, salin ID itu ke `owners`. |
 | `$eval ... dimatikan` | Tambahkan `eval: true` dan `owners: ['ID_KAMU']` pada `new Bot({...})`. |
 | Event ban / voice tidak jalan | Intent `GuildModeration` / `GuildVoiceStates` sudah aktif secara bawaan; jika kamu mengatur `intents` sendiri, tambahkan keduanya. |
 
 ---
 
-## 16. Daftar semua fungsi
+## 17. Daftar semua fungsi
 
 Tanda `?` berarti argumen opsional. Daftar ini dibuat otomatis dari kode (`npm run docs`).
 
@@ -654,15 +820,19 @@ Tanda `?` berarti argumen opsional. Daftar ini dibuat otomatis dari kode (`npm r
 | `$setUserVar[nama;nilai;userID?]` | Simpan variabel user (harus dideklarasikan dengan bot.variables) |
 | `$getUserVar[nama;userID?]` | Baca variabel user |
 | `$resetUserVar[nama;userID?]` | Kembalikan variabel user ke nilai awal |
+| `$incUserVar[nama;jumlah;userID?]` | Tambah variabel user berupa angka (jumlah negatif = kurangi). Aman dari tabrakan antar command. Tidak menampilkan apa pun |
 | `$setServerVar[nama;nilai;serverID?]` | Simpan variabel server (harus dideklarasikan dengan bot.variables) |
 | `$getServerVar[nama;serverID?]` | Baca variabel server |
 | `$resetServerVar[nama;serverID?]` | Kembalikan variabel server ke nilai awal |
+| `$incServerVar[nama;jumlah;serverID?]` | Tambah variabel server berupa angka (jumlah negatif = kurangi). Aman dari tabrakan antar command. Tidak menampilkan apa pun |
 | `$setChannelVar[nama;nilai;channelID?]` | Simpan variabel channel (harus dideklarasikan dengan bot.variables) |
 | `$getChannelVar[nama;channelID?]` | Baca variabel channel |
 | `$resetChannelVar[nama;channelID?]` | Kembalikan variabel channel ke nilai awal |
+| `$incChannelVar[nama;jumlah;channelID?]` | Tambah variabel channel berupa angka (jumlah negatif = kurangi). Aman dari tabrakan antar command. Tidak menampilkan apa pun |
 | `$setGlobalVar[nama;nilai]` | Simpan variabel global |
 | `$getGlobalVar[nama]` | Baca variabel global |
 | `$resetGlobalVar[nama]` | Kembalikan variabel global ke nilai awal |
+| `$incGlobalVar[nama;jumlah]` | Tambah variabel global berupa angka (jumlah negatif = kurangi) |
 
 ### Embed
 
@@ -725,7 +895,7 @@ Tanda `?` berarti argumen opsional. Daftar ini dibuat otomatis dari kode (`npm r
 | `$addTextFile[namaFile;isi]` | Lampirkan file teks buatan sendiri (maks 1 MB) |
 | `$poll[pertanyaan;jam;multi;opsi1;opsi2;...]` | Buat polling (jam 1-768, multi = true/false, 2-10 opsi) |
 | `$sendWebhook[webhookURL;teks;username?;avatarURL?]` | Kirim pesan lewat URL webhook Discord |
-| `$createThread[nama;messageID?;arsipOtomatisMenit?]` | Buat thread (dari pesan bila messageID diisi). Arsip: 60/1440/4320/10080. Mengembalikan ID thread |
+| `$createThread[nama;messageID?;arsipOtomatisMenit?;channelID?]` | Buat thread (dari pesan bila messageID diisi; channelID = channel tempat pesan itu, bawaan channel ini). Arsip: 60/1440/4320/10080. Mengembalikan ID thread |
 | `$archiveThread[threadID?;kunci?]` | Arsipkan thread (kunci = true untuk sekalian dikunci) |
 | `$addThreadMember[userID;threadID?]` | Tambahkan user ke thread |
 | `$removeThreadMember[userID;threadID?]` | Keluarkan user dari thread |
@@ -786,10 +956,15 @@ Tanda `?` berarti argumen opsional. Daftar ini dibuat otomatis dari kode (`npm r
 
 ## Yang belum didukung
 
-Package ini belum mencakup seluruh discord.js. Belum ada: **voice/musik** (memutar audio), **sharding**, **AutoMod rules**, **stiker**, pengaturan permission per-channel yang rinci, dan Components V2. Untuk itu pakai `bot.client` (client discord.js asli) atau tambahkan fungsi lewat `bot.addFunction`.
+Package ini belum mencakup seluruh discord.js. Belum ada: adapter database selain JSON dan MongoDB (SQLite, Redis, dll.; bisa dibuat sendiri, lihat bagian 12), **voice/musik** (memutar audio), **sharding**, **AutoMod rules**, **stiker**, pengaturan permission per-channel yang rinci, dan Components V2. Untuk itu pakai `bot.client` (client discord.js asli) atau tambahkan fungsi lewat `bot.addFunction`.
 
 ## Riwayat versi
 
+- **1.3.0**: plugin voice/musik (`@tryty/easydc-js/voice`, butuh Lavalink + `shoukaku`). Fungsi stop musik bernama `$stopMusic` karena `$stop` sudah dipakai fungsi inti.
+- **1.2.3**: `owners` divalidasi (angka besar ditolak, mention/spasi dirapikan); penolakan owner mencatat ID pengirim ke konsol.
+- **1.2.2**: nama package menjadi `@tryty/easydc-js`; panduan pemasangan dari file lokal.
+- **1.2.1**: `bot.selfTestCommand()` (`!selftest`, tes otomatis di Discord asli); `$createThread` bisa membuat thread dari pesan di channel lain (argumen ke-4).
+- **1.2.0**: sistem plugin (`bot.use`, `bot.setDatabase`), plugin **MongoDB** (`@tryty/easydc-js/mongodb`), `copyDatabase` untuk migrasi dari JSON, `$incUserVar` dan kawan-kawannya (tambah angka dengan aman). `bot.getVar/setVar/resetVar` kini async.
 - **1.1.0**: `$unban` dan manajemen server (channel, role, undangan, emoji, event, voice), edit/hapus/pin pesan, lampiran, poll, webhook, thread & forum, modal, autocomplete, context menu, select user/role/channel, 9 event baru, `$eval` / `$jsEval` / `bot.evalCommand`. Intent bawaan bertambah `GuildModeration` dan `GuildVoiceStates`.
 - **1.0.0**: rilis pertama.
 

package/examples/basic.js

@@ -1,5 +1,5 @@
 // Jalankan: TOKEN=token_bot_kamu node examples/basic.js
-const { Bot } = require('easydc-js'); // saat dicoba dari folder ini: require('../src')
+const { Bot } = require('@tryty/easydc-js'); // saat dicoba dari folder ini: require('../src')
 
 const bot = new Bot({
   token: process.env.TOKEN,

package/examples/mongo.js

@@ -0,0 +1,44 @@
+// Bot dengan database MongoDB.
+// Pasang dulu: npm install @tryty/easydc-js discord.js mongodb
+// Jalankan:   TOKEN=token_bot MONGO_URI="mongodb+srv://..." node examples/mongo.js
+const { Bot } = require('@tryty/easydc-js'); // saat dicoba dari folder ini: require('../src')
+const { mongodb } = require('@tryty/easydc-js/mongodb'); // saat dicoba dari folder ini: require('../src/plugins/mongodb')
+
+const bot = new Bot({ token: process.env.TOKEN, prefix: '!', timezone: 'Asia/Jakarta' });
+
+bot.use(mongodb({
+  uri: process.env.MONGO_URI,
+  dbName: 'botku',
+  // cache: false,   // aktifkan baris ini jika bot dijalankan di lebih dari satu proses/server
+}));
+
+bot.variables({ uang: 100 });
+
+bot.command({ name: 'uang', code: '💰 $username punya $numberSeparator[$getUserVar[uang];.] koin' });
+
+bot.command({
+  name: 'kerja',
+  code: `
+$cooldown[1m;Istirahat dulu, tunggu %time%.]
+$incUserVar[uang;$random[10;50]]
+Kamu bekerja! Uangmu sekarang $getUserVar[uang]
+`,
+});
+
+bot.command({
+  name: 'kirim',
+  code: `
+$argsCheck[2;Format: !kirim @user jumlah]
+$onlyIf[$mentioned[1]!=;Mention user tujuan.]
+$onlyIf[$isNumber[$message[2]]==true&&$message[2]>0;Jumlah harus angka lebih dari 0.]
+$onlyIf[$getUserVar[uang]>=$message[2];Uangmu tidak cukup.]
+$incUserVar[uang;-$message[2]]
+$incUserVar[uang;$message[2];$mentioned[1]]
+✅ Terkirim $message[2] koin ke <@$mentioned[1]>
+`,
+});
+
+bot.connect().then(() => console.log('Bot online, database terhubung.')).catch((e) => {
+  console.error(e.message);
+  process.exit(1);
+});

package/index.d.ts

@@ -15,7 +15,7 @@ export interface BotOptions {
   handleSignals?: boolean;
   /** Nyalakan $eval / $jsEval / bot.evalCommand (hanya untuk ID di `owners`). Bawaan: false */
   eval?: boolean;
-  database?: { path?: string; memory?: boolean; saveDelay?: number } | Database;
+  database?: { path?: string; memory?: boolean; saveDelay?: number } | DatabaseAdapter;
   messages?: { cooldown?: string; error?: string };
   status?: { text: string; type?: 'Playing' | 'Streaming' | 'Listening' | 'Watching' | 'Competing'; status?: 'online' | 'idle' | 'dnd' | 'invisible' };
   onError?: (error: Error, ctx: Context) => unknown;
@@ -70,7 +70,19 @@ export class Context {
   rawArgs: string;
 }
 
-export class Database {
+/** Adapter database: hanya get/set/delete yang wajib. Nilai balik boleh Promise. */
+export interface DatabaseAdapter {
+  get(key: string): unknown | Promise<unknown>;
+  set(key: string, value: unknown): unknown | Promise<unknown>;
+  delete(key: string): unknown | Promise<unknown>;
+  has?(key: string): boolean | Promise<boolean>;
+  keys?(prefix?: string): string[] | Promise<string[]>;
+  flush?(): unknown | Promise<unknown>;
+  connect?(): Promise<void>;
+  close?(): unknown | Promise<unknown>;
+}
+
+export class Database implements DatabaseAdapter {
   constructor(options?: { path?: string; memory?: boolean; saveDelay?: number });
   get(key: string): unknown;
   set(key: string, value: unknown): void;
@@ -78,12 +90,18 @@ export class Database {
   delete(key: string): boolean;
   keys(prefix?: string): string[];
   flush(): void;
+  close(): void;
 }
 
+export function copyDatabase(from: DatabaseAdapter, to: DatabaseAdapter, options?: { overwrite?: boolean; prefix?: string }): Promise<{ copied: number; skipped: number }>;
+
+export type Plugin = ((bot: Bot, options?: unknown) => void) | { name?: string; install(bot: Bot, options?: unknown): void };
+
 export class Bot {
   constructor(options?: BotOptions);
   client: Client | null;
-  db: Database;
+  db: DatabaseAdapter;
+  plugins: Map<string, unknown>;
   command(def: CommandDef): this;
   slashCommand(def: SlashDef): this;
   button(def: ComponentDef): this;
@@ -93,6 +111,8 @@ export class Bot {
   contextMenu(def: ContextMenuDef): this;
   /** Pasang command eval siap pakai (butuh `eval: true` dan `owners`). */
   evalCommand(def?: { name?: string; aliases?: string[] }): this;
+  /** Pasang command tes otomatis di Discord asli (butuh `owners`). `ui: true` menambah /tesauto & menu klik-kanan uji. */
+  selfTestCommand(def?: { name?: string; aliases?: string[]; ui?: boolean }): this;
   event(def: EventDef): this;
   onMemberBan(code: string | Omit<EventDef, 'type'>): this;
   onMemberUnban(code: string | Omit<EventDef, 'type'>): this;
@@ -117,9 +137,12 @@ export class Bot {
   addFunction(fn: CustomFunction): this;
   loadCommands(dir: string): this;
   validate(): true;
-  getVar(scope: 'user' | 'server' | 'channel' | 'global', name: string, id?: string | null): string;
-  setVar(scope: 'user' | 'server' | 'channel' | 'global', name: string, value: unknown, id?: string | null): void;
-  resetVar(scope: 'user' | 'server' | 'channel' | 'global', name: string, id?: string | null): void;
+  use(plugin: Plugin, options?: unknown): this;
+  setDatabase(adapter: DatabaseAdapter): this;
+  getVar(scope: 'user' | 'server' | 'channel' | 'global', name: string, id?: string | null): Promise<string>;
+  setVar(scope: 'user' | 'server' | 'channel' | 'global', name: string, value: unknown, id?: string | null): Promise<void>;
+  resetVar(scope: 'user' | 'server' | 'channel' | 'global', name: string, id?: string | null): Promise<void>;
+  incVar(scope: 'user' | 'server' | 'channel' | 'global', name: string, amount: number | string, id?: string | null): Promise<string>;
   connect(token?: string): Promise<this>;
   destroy(): Promise<void>;
 }

package/mongodb.d.ts

@@ -0,0 +1,31 @@
+import type { Database } from './index';
+
+export interface MongoOptions {
+  /** Alamat MongoDB, mis. process.env.MONGO_URI. Wajib kecuali `client` diisi. */
+  uri?: string;
+  dbName?: string;
+  /** Bawaan: "easydc" */
+  collection?: string;
+  /** Bawaan true. Matikan bila lebih dari satu proses bot memakai database yang sama. */
+  cache?: boolean;
+  cacheLimit?: number;
+  /** MongoClient milik sendiri (tidak ditutup otomatis). */
+  client?: unknown;
+  driver?: unknown;
+  clientOptions?: Record<string, unknown>;
+}
+
+export class MongoDatabase {
+  constructor(options: MongoOptions);
+  connect(): Promise<void>;
+  get(key: string): Promise<string | undefined>;
+  has(key: string): Promise<boolean>;
+  set(key: string, value: unknown): Promise<void>;
+  delete(key: string): Promise<boolean>;
+  keys(prefix?: string): Promise<string[]>;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+}
+
+/** Plugin: bot.use(mongodb({ uri, dbName })) */
+export function mongodb(options: MongoOptions): { name: string; install(bot: unknown): void };

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@tryty/easydc-js",
-  "version": "1.1.0",
-  "description": "Bot Discord super mudah di atas discord.js: tulis perintah dengan sintaks $fungsi[arg] ala aoi.js.",
+  "version": "1.2.2",
+  "description": "Super easy Discord bot on top of discord.js: write commands with $function[arg] syntax.",
   "main": "src/index.js",
   "types": "index.d.ts",
   "files": [
     "src",
     "examples",
     "index.d.ts",
+    "mongodb.d.ts",
+    "voice.d.ts",
     "README.md",
     "LICENSE"
   ],
@@ -16,11 +18,15 @@
     "docs": "node scripts/gen-docs.js"
   },
   "keywords": [
+    "bot",
     "discord",
     "discord.js",
-    "bot",
-    "aoi.js",
     "easy",
+    "lavalink",
+    "mongodb",
+    "music",
+    "plugin",
+    "voice",
     "wrapper"
   ],
   "author": "",
@@ -30,5 +36,32 @@
   },
   "dependencies": {
     "discord.js": "^14.16.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./mongodb": {
+      "types": "./mongodb.d.ts",
+      "default": "./src/plugins/mongodb.js"
+    },
+    "./package.json": "./package.json",
+    "./voice": {
+      "types": "./voice.d.ts",
+      "default": "./src/plugins/voice.js"
+    }
+  },
+  "peerDependencies": {
+    "mongodb": ">=5.0.0",
+    "shoukaku": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "mongodb": {
+      "optional": true
+    },
+    "shoukaku": {
+      "optional": true
+    }
   }
 }