@tryty/easydc-js 0.0.0-stage → 1.2.0

package/src/functions/control.js

@@ -0,0 +1,142 @@
+'use strict';
+const { BotError, Stop } = require('../errors');
+const { parseTime, formatDuration } = require('../util');
+const { f, list, cleanId } = require('./helpers');
+
+const MAX_WAIT = 60 * 1000;
+const MAX_DELETE_IN = 24 * 60 * 60 * 1000;
+
+const msgOf = async (api, args, i) => (args[i] ? api.run(args[i]) : '');
+
+// Catatan: semua fungsi "only*" bersifat lazy supaya pesan penolakan (arg terakhir)
+// tidak ikut dieksekusi saat syaratnya terpenuhi.
+module.exports = [
+  // Struktur (ditangani parser/interpreter, definisi ini untuk validasi & dokumentasi)
+  f('if', { b: 'required', min: 1, max: 1, lazy: true, s: '[kondisi]', d: 'Mulai blok kondisi. Tutup dengan $endif' }, () => ''),
+  f('elseif', { b: 'required', min: 1, max: 1, lazy: true, s: '[kondisi]', d: 'Kondisi alternatif' }, () => ''),
+  f('else', { b: 'none', lazy: true, d: 'Jika semua kondisi sebelumnya salah' }, () => ''),
+  f('endif', { b: 'none', lazy: true, d: 'Menutup blok $if' }, () => ''),
+
+  f('stop', { max: 1, lazy: true, s: '[pesan?]', d: 'Hentikan eksekusi (opsional kirim pesan)' },
+    async (ctx, args, api) => { throw new Stop(await msgOf(api, args, 0)); }),
+  f('onlyIf', { b: 'required', min: 1, max: 2, lazy: true, s: '[kondisi;pesan?]', d: 'Lanjut hanya jika kondisi benar' },
+    async (ctx, args, api) => {
+      if (await api.cond(args[0])) return '';
+      throw new Stop(await msgOf(api, args, 1));
+    }),
+  f('onlyPerms', { b: 'required', min: 1, max: 2, lazy: true, s: '[Izin1,Izin2;pesan?]', d: 'Lanjut hanya jika pengirim punya semua izin (mis. BanMembers)' },
+    async (ctx, args, api) => {
+      const perms = list(await api.run(args[0]));
+      if (!perms.length) throw new BotError('Izin belum diisi');
+      if (ctx.member?.permissions?.has(perms)) return '';
+      throw new Stop(await msgOf(api, args, 1));
+    }),
+  f('onlyBotPerms', { b: 'required', min: 1, max: 2, lazy: true, s: '[Izin1,Izin2;pesan?]', d: 'Lanjut hanya jika bot punya izin tersebut di server' },
+    async (ctx, args, api) => {
+      const perms = list(await api.run(args[0]));
+      if (!perms.length) throw new BotError('Izin belum diisi');
+      if (ctx.guild?.members?.me?.permissions?.has(perms)) return '';
+      throw new Stop(await msgOf(api, args, 1));
+    }),
+  f('onlyAdmin', { max: 1, lazy: true, s: '[pesan?]', d: 'Lanjut hanya jika pengirim administrator' },
+    async (ctx, args, api) => {
+      if (ctx.member?.permissions?.has('Administrator')) return '';
+      throw new Stop(await msgOf(api, args, 0));
+    }),
+  f('onlyOwner', { max: 1, lazy: true, s: '[pesan?]', d: 'Lanjut hanya jika pengirim ada di opsi owners' },
+    async (ctx, args, api) => {
+      if (ctx.bot.options.owners.includes(ctx.user?.id)) return '';
+      throw new Stop(await msgOf(api, args, 0));
+    }),
+  f('onlyForIDs', { b: 'required', min: 1, max: 2, lazy: true, s: '[id1,id2;pesan?]', d: 'Lanjut hanya untuk user dengan ID tertentu' },
+    async (ctx, args, api) => {
+      const ids = list(await api.run(args[0])).map(cleanId);
+      if (ids.includes(ctx.user?.id)) return '';
+      throw new Stop(await msgOf(api, args, 1));
+    }),
+  f('onlyInServer', { max: 1, lazy: true, s: '[pesan?]', d: 'Lanjut hanya jika dipakai di server (bukan DM)' },
+    async (ctx, args, api) => {
+      if (ctx.guild) return '';
+      throw new Stop(await msgOf(api, args, 0));
+    }),
+  f('argsCheck', { b: 'required', min: 1, max: 2, lazy: true, s: '[syarat;pesan?]', d: 'Cek jumlah argumen. "2" = minimal 2; juga >=1 <=3 >1 <3 =2' },
+    async (ctx, args, api) => {
+      const spec = (await api.run(args[0])).trim();
+      const m = /^(>=|<=|>|<|=)?\s*(\d+)$/.exec(spec);
+      if (!m) throw new BotError(`Syarat "${spec}" tidak valid (contoh: 2, >=1, <3, =2)`);
+      const n = Number(m[2]);
+      const c = ctx.args.length;
+      let ok;
+      switch (m[1]) {
+        case '>': ok = c > n; break;
+        case '<': ok = c < n; break;
+        case '<=': ok = c <= n; break;
+        case '=': ok = c === n; break;
+        default: ok = c >= n;
+      }
+      if (ok) return '';
+      throw new Stop(await msgOf(api, args, 1));
+    }),
+  f('cooldown', { b: 'required', min: 1, max: 2, lazy: true, s: '[waktu;pesan?]', d: 'Cooldown per user per command. %time% di pesan = sisa waktu' },
+    async (ctx, args, api) => {
+      const ms = parseTime(await api.run(args[0]));
+      const key = `${ctx.command?.key ?? ctx.command?.name ?? 'anon'}:${ctx.user?.id ?? 'none'}`;
+      const now = Date.now();
+      const cds = ctx.bot.cooldowns;
+      const until = cds.get(key);
+      if (until && until > now) {
+        const remaining = formatDuration(Math.ceil((until - now) / 1000) * 1000);
+        const custom = args[1] ? await api.run(args[1]) : ctx.bot.options.messages.cooldown;
+        throw new Stop(custom.replace(/%time%/g, remaining));
+      }
+      cds.set(key, now + ms);
+      if (cds.size > 5000) for (const [k, v] of cds) if (v <= now) cds.delete(k);
+      return '';
+    }),
+
+  f('wait', { b: 'required', min: 1, max: 1, s: '[waktu]', d: 'Tunggu sebentar (maks 60 detik)' },
+    async (ctx, [t]) => {
+      const ms = parseTime(t);
+      if (ms > MAX_WAIT) throw new BotError('Waktu tunggu maksimal 60 detik');
+      await new Promise((resolve) => { setTimeout(resolve, ms); });
+      return '';
+    }),
+  f('deleteCommand', { b: 'none', d: 'Hapus pesan perintah milik pengirim setelah dijawab' },
+    (ctx) => { ctx.deleteCommand = true; return ''; }),
+  f('deleteIn', { b: 'required', min: 1, max: 1, s: '[waktu]', d: 'Hapus jawaban bot setelah waktu tertentu (maks 24 jam)' },
+    (ctx, [t]) => {
+      const ms = parseTime(t);
+      if (ms > MAX_DELETE_IN) throw new BotError('Waktu maksimal 24 jam');
+      ctx.deleteIn = ms;
+      return '';
+    }),
+  f('ephemeral', { b: 'none', d: 'Slash/tombol: jawaban hanya terlihat oleh pengguna' },
+    (ctx) => { ctx.ephemeral = true; return ''; }),
+  f('reply', { b: 'none', d: 'Jawab dengan fitur reply pada pesan perintah' },
+    (ctx) => { ctx.useReply = true; return ''; }),
+  f('update', { b: 'none', d: 'Tombol/select: ubah pesan asal, bukan kirim pesan baru' },
+    (ctx) => { ctx.update = true; return ''; }),
+  f('typing', { b: 'none', d: 'Tampilkan "sedang mengetik"' },
+    async (ctx) => { await ctx.channel?.sendTyping?.(); return ''; }),
+  f('defer', { b: 'none', d: 'Slash/tombol: tunda jawaban (untuk proses > 3 detik). Taruh $ephemeral sebelum ini bila perlu' },
+    async (ctx) => {
+      const it = ctx.interaction;
+      if (!it || it.deferred || it.replied) return '';
+      if (ctx.update && typeof it.deferUpdate === 'function') await it.deferUpdate();
+      else await it.deferReply(ctx.ephemeral ? { flags: 64 } : {});
+      return '';
+    }),
+
+  f('let', { b: 'required', min: 2, max: 2, s: '[nama;nilai]', d: 'Simpan variabel sementara (hanya selama command berjalan)' },
+    (ctx, [name, value]) => {
+      if (!name.trim()) throw new BotError('Nama variabel kosong');
+      ctx.temp.set(name.trim(), value);
+      return '';
+    }),
+  f('get', { b: 'required', min: 1, max: 1, s: '[nama]', d: 'Ambil variabel sementara dari $let' },
+    (ctx, [name]) => {
+      const key = name.trim();
+      if (!ctx.temp.has(key)) throw new BotError(`Variabel sementara "${key}" belum dibuat dengan $let`);
+      return ctx.temp.get(key);
+    }),
+];

package/src/functions/embed.js

@@ -0,0 +1,71 @@
+'use strict';
+const { BotError } = require('../errors');
+const { f, has, num, url, limit } = require('./helpers');
+
+const COLORS = {
+  red: 0xed4245, green: 0x57f287, blue: 0x3498db, yellow: 0xfee75c, orange: 0xe67e22,
+  purple: 0x9b59b6, pink: 0xeb459e, white: 0xffffff, black: 0x000000, grey: 0x95a5a6,
+  gray: 0x95a5a6, blurple: 0x5865f2,
+};
+
+function parseColor(v) {
+  const s = String(v).trim().toLowerCase();
+  if (s === 'random') return Math.floor(Math.random() * 0xffffff);
+  if (Object.hasOwn(COLORS, s)) return COLORS[s];
+  const m = /^(?:#|0x)?([0-9a-f]{6})$/.exec(s);
+  if (!m) throw new BotError(`Warna "${v}" tidak valid (contoh: #5865F2, red, random)`);
+  return parseInt(m[1], 16);
+}
+
+module.exports = [
+  f('newEmbed', { b: 'none', d: 'Mulai embed baru (embed pertama dibuat otomatis). Maks 10' },
+    (ctx) => { ctx.newEmbed(); return ''; }),
+  f('title', { b: 'required', min: 1, max: 1, s: '[teks]', d: 'Judul embed (maks 256)' },
+    (ctx, [t]) => { ctx.currentEmbed().title = limit('title', t, 256); return ''; }),
+  f('embedURL', { b: 'required', min: 1, max: 1, s: '[url]', d: 'Tautan pada judul embed' },
+    (ctx, [u]) => { ctx.currentEmbed().url = url(u, 'url'); return ''; }),
+  f('description', { b: 'required', min: 1, max: 1, s: '[teks]', d: 'Isi embed (maks 4096)' },
+    (ctx, [t]) => { ctx.currentEmbed().description = limit('description', t, 4096); return ''; }),
+  f('color', { b: 'required', min: 1, max: 1, s: '[#hex|nama|random]', d: 'Warna embed' },
+    (ctx, [c]) => { ctx.currentEmbed().color = parseColor(c); return ''; }),
+  f('footer', { b: 'required', min: 1, max: 2, s: '[teks;ikonURL?]', d: 'Footer embed (maks 2048)' },
+    (ctx, [t, icon]) => {
+      const footer = { text: limit('footer', t, 2048) };
+      if (has(icon)) footer.icon_url = url(icon, 'ikon footer');
+      ctx.currentEmbed().footer = footer;
+      return '';
+    }),
+  f('author', { b: 'required', min: 1, max: 3, s: '[nama;ikonURL?;url?]', d: 'Penulis embed (maks 256)' },
+    (ctx, [name, icon, link]) => {
+      const author = { name: limit('author', name, 256) };
+      if (has(icon)) author.icon_url = url(icon, 'ikon author');
+      if (has(link)) author.url = url(link, 'url author');
+      ctx.currentEmbed().author = author;
+      return '';
+    }),
+  f('thumbnail', { b: 'required', min: 1, max: 1, s: '[url]', d: 'Gambar kecil embed' },
+    (ctx, [u]) => { ctx.currentEmbed().thumbnail = { url: url(u, 'thumbnail') }; return ''; }),
+  f('image', { b: 'required', min: 1, max: 1, s: '[url]', d: 'Gambar besar embed' },
+    (ctx, [u]) => { ctx.currentEmbed().image = { url: url(u, 'image') }; return ''; }),
+  f('addField', { b: 'required', min: 2, max: 3, s: '[nama;isi;inline?]', d: 'Tambah field (maks 25; inline = true/false)' },
+    (ctx, [name, value, inline]) => {
+      const e = ctx.currentEmbed();
+      e.fields ??= [];
+      if (e.fields.length >= 25) throw new BotError('Maksimal 25 field per embed');
+      if (!name.trim() || !value.trim()) throw new BotError('Nama dan isi field tidak boleh kosong');
+      e.fields.push({
+        name: limit('nama field', name, 256),
+        value: limit('isi field', value, 1024),
+        inline: has(inline) && ['true', 'yes', '1'].includes(inline.trim().toLowerCase()),
+      });
+      return '';
+    }),
+  f('addTimestamp', { max: 1, s: '[ms?]', d: 'Tambah cap waktu di embed (default: sekarang)' },
+    (ctx, [ms]) => {
+      const t = has(ms) ? num(ms, 'ms') : Date.now();
+      ctx.currentEmbed().timestamp = new Date(t).toISOString();
+      return '';
+    }),
+];
+
+module.exports.parseColor = parseColor;

package/src/functions/eval.js

@@ -0,0 +1,73 @@
+'use strict';
+const util = require('node:util');
+const { BotError, Stop } = require('../errors');
+const { parse } = require('../parser');
+const { f } = require('./helpers');
+
+const AsyncFunction = Object.getPrototypeOf(async () => {}).constructor;
+const MAX_OUTPUT = 1800;
+const MAX_DEPTH = 3;
+const ZWSP = '​';
+
+function guard(ctx, label) {
+  if (!ctx.bot.options.eval) {
+    throw new Stop(`❌ ${label} dimatikan. Nyalakan dengan new Bot({ eval: true, owners: ['ID_KAMU'] }).`);
+  }
+  if (!ctx.bot.options.owners.includes(ctx.user?.id)) throw new Stop('❌ Hanya owner bot yang boleh memakai eval.');
+}
+
+function clean(ctx, text) {
+  let out = String(text);
+  const secrets = [ctx.bot.options.token, ctx.client?.token].filter((s) => typeof s === 'string' && s.length > 8);
+  for (const s of secrets) out = out.split(s).join('[TOKEN DISENSOR]');
+  out = out.replace(/```/g, `\`${ZWSP}\`\``);
+  return out.length > MAX_OUTPUT ? `${out.slice(0, MAX_OUTPUT)}\n... (dipotong)` : out;
+}
+
+function compile(code, names) {
+  try {
+    return new AsyncFunction(...names, `return (\n${code}\n);`); // ekspresi tunggal
+  } catch (e) {
+    if (!(e instanceof SyntaxError)) throw e;
+    return new AsyncFunction(...names, code); // beberapa pernyataan (pakai return untuk hasil)
+  }
+}
+
+// PERINGATAN: eval memberi akses PENUH ke bot dan mesin. Hanya aktif bila opsi `eval: true`
+// DAN pengirim ada di `owners`. Jangan pernah mengaktifkannya jika owners diisi orang yang tidak dipercaya.
+module.exports = [
+  f('eval', { b: 'required', min: 1, max: 1, s: '[kode]', d: 'Jalankan kode versi port ($fungsi) dari teks saat berjalan. Khusus owner, butuh opsi eval: true' },
+    async (ctx, [code]) => {
+      guard(ctx, '$eval');
+      if (!code.trim()) return '❌ Kode kosong.';
+      if ((ctx.evalDepth ?? 0) >= MAX_DEPTH) throw new BotError('$eval bersarang terlalu dalam');
+      ctx.evalDepth = (ctx.evalDepth ?? 0) + 1;
+      try {
+        const text = await ctx.bot.interpreter.run(parse(code, ctx.bot.registry), ctx);
+        return clean(ctx, text);
+      } catch (e) {
+        if (e instanceof Stop) throw e;
+        return clean(ctx, `❌ ${e.message}`);
+      } finally {
+        ctx.evalDepth -= 1;
+      }
+    }),
+  f('jsEval', { b: 'required', min: 1, max: 1, s: '[kodeJavaScript]', d: 'Jalankan kode discord.js/JavaScript asli. Variabel: ctx client bot guild channel message user member interaction discord db require. Khusus owner, butuh opsi eval: true' },
+    async (ctx, [code]) => {
+      guard(ctx, '$jsEval');
+      if (!code.trim()) return '❌ Kode kosong.';
+      let discord = null;
+      try { discord = ctx.bot._discord(); } catch { /* discord.js belum terpasang di mesin ini */ }
+      const scope = {
+        ctx, client: ctx.client, bot: ctx.bot, guild: ctx.guild, channel: ctx.channel, message: ctx.message,
+        user: ctx.user, member: ctx.member, interaction: ctx.interaction, discord, db: ctx.bot.db, require,
+      };
+      try {
+        const result = await compile(code, Object.keys(scope))(...Object.values(scope));
+        const text = typeof result === 'string' ? result : util.inspect(result, { depth: 1, maxArrayLength: 20, breakLength: 80 });
+        return clean(ctx, text);
+      } catch (e) {
+        return clean(ctx, `❌ ${e?.name ?? 'Error'}: ${e?.message ?? e}`);
+      }
+    }),
+];

package/src/functions/helpers.js

@@ -0,0 +1,86 @@
+'use strict';
+const { BotError } = require('../errors');
+
+const has = (v) => v !== undefined && v !== null && String(v) !== '';
+const truthy = (v) => ['true', 'yes', '1', 'on'].includes(String(v ?? '').trim().toLowerCase());
+const cleanId = (v) => String(v ?? '').trim().replace(/^<(?:@!?|@&|#)(\d+)>$/, '$1');
+const list = (v) => String(v ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+
+function num(v, label, { min = -Infinity, max = Infinity, int = false } = {}) {
+  const s = String(v ?? '').trim();
+  const n = Number(s);
+  if (s === '' || !Number.isFinite(n)) throw new BotError(`${label} harus berupa angka (diberi "${s}")`);
+  if (int && !Number.isInteger(n)) throw new BotError(`${label} harus bilangan bulat (diberi "${s}")`);
+  if (n < min || n > max) throw new BotError(`${label} harus di antara ${min} dan ${max} (diberi ${s})`);
+  return n;
+}
+
+function url(v, label) {
+  const s = String(v ?? '').trim();
+  if (!/^https?:\/\/\S+$/i.test(s)) throw new BotError(`${label} harus URL http(s) yang valid (diberi "${s}")`);
+  return s;
+}
+
+function limit(label, value, max) {
+  const s = String(value);
+  if (s.length > max) throw new BotError(`${label} terlalu panjang (${s.length} > ${max} karakter)`);
+  return s;
+}
+
+async function fetchChannel(ctx, id) {
+  const clean = cleanId(id);
+  const cached = ctx.client.channels.cache.get(clean);
+  if (cached) return cached;
+  try {
+    const ch = await ctx.client.channels.fetch(clean);
+    if (ch) return ch;
+  } catch { /* jatuh ke error di bawah */ }
+  throw new BotError(`Channel "${clean}" tidak ditemukan`);
+}
+
+/** Channel dari ID, atau channel saat ini bila ID kosong. */
+async function channelOrCurrent(ctx, id) {
+  if (has(id)) return fetchChannel(ctx, id);
+  if (!ctx.channel) throw new BotError('Tidak ada channel pada konteks ini, isi channelID');
+  return ctx.channel;
+}
+
+async function fetchMessage(ctx, messageId, channelId) {
+  const ch = await channelOrCurrent(ctx, channelId);
+  if (!ch.messages || typeof ch.messages.fetch !== 'function') throw new BotError('Channel itu tidak punya pesan');
+  try {
+    return await ch.messages.fetch(String(messageId).trim());
+  } catch (e) {
+    throw new BotError(`Pesan "${messageId}" tidak ditemukan`, { cause: e });
+  }
+}
+
+function getRole(ctx, id) {
+  const clean = cleanId(id);
+  const role = ctx.requireGuild().roles.cache.get(clean);
+  if (!role) throw new BotError(`Role "${clean}" tidak ditemukan`);
+  return role;
+}
+
+/**
+ * Buat definisi fungsi.
+ * spec: b = 'none' | 'optional' | 'required' (tanda kurung), min, max, lazy,
+ *       s = contoh sintaks, d = deskripsi (dipakai untuk dokumentasi otomatis)
+ */
+function f(name, spec, run) {
+  if (typeof spec === 'function') { run = spec; spec = {}; }
+  const brackets = spec.b ?? 'optional';
+  return {
+    name: name.toLowerCase(),
+    display: `$${name}`,
+    brackets,
+    min: spec.min ?? 0,
+    max: brackets === 'none' ? 0 : (spec.max ?? Infinity),
+    lazy: !!spec.lazy,
+    sig: spec.s ?? '',
+    doc: spec.d ?? '',
+    run,
+  };
+}
+
+module.exports = { f, has, truthy, cleanId, list, num, url, limit, fetchChannel, channelOrCurrent, fetchMessage, getRole };

package/src/functions/index.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const CATEGORIES = [
+  ['Info (user, server, bot, pesan, waktu)', require('./info')],
+  ['Teks, matematika & pengecekan', require('./text')],
+  ['Kontrol alur & batasan', require('./control')],
+  ['Variabel & database', require('./vars')],
+  ['Embed', require('./embed')],
+  ['Tombol & select menu', require('./components')],
+  ['Aksi & moderasi', require('./actions')],
+  ['Pesan, lampiran, polling, thread & webhook', require('./messages')],
+  ['Manajemen server (ban, channel, role, undangan, emoji, event, voice)', require('./manage')],
+  ['Modal, autocomplete & sasaran', require('./interact')],
+  ['Eval (khusus owner)', require('./eval')],
+];
+
+/** Map(namaLowercase -> definisi). Dilempar error bila ada nama ganda. */
+function createRegistry() {
+  const map = new Map();
+  for (const [category, defs] of CATEGORIES) {
+    for (const def of defs) {
+      if (map.has(def.name)) throw new Error(`Fungsi ganda: ${def.display}`);
+      map.set(def.name, { ...def, category });
+    }
+  }
+  return map;
+}
+
+module.exports = { createRegistry, CATEGORIES };

package/src/functions/info.js

@@ -0,0 +1,117 @@
+'use strict';
+const { BotError } = require('../errors');
+const { formatDuration, formatDate } = require('../util');
+const { f, has, truthy, cleanId, num } = require('./helpers');
+
+const emojiText = (e) => {
+  if (!e) return '';
+  if (e.id) return `<${e.animated ? 'a' : ''}:${e.name}:${e.id}>`;
+  return e.name ?? '';
+};
+
+module.exports = [
+  // ---- User -------------------------------------------------------------------
+  f('username', { max: 1, s: '[userID?]', d: 'Username (tanpa ID = pengirim)' },
+    async (ctx, [id]) => (await ctx.fetchUser(id)).username),
+  f('usertag', { max: 1, s: '[userID?]', d: 'Tag user' },
+    async (ctx, [id]) => { const u = await ctx.fetchUser(id); return u.tag ?? u.username; }),
+  f('displayName', { max: 1, s: '[userID?]', d: 'Nama tampilan (nickname server / nama global / username)' },
+    async (ctx, [id]) => {
+      const u = await ctx.fetchUser(id);
+      const m = await ctx.tryMember(id);
+      return m?.displayName ?? u.globalName ?? u.username;
+    }),
+  f('nickname', { max: 1, s: '[userID?]', d: 'Nickname di server (kosong -> username)' },
+    async (ctx, [id]) => {
+      const u = await ctx.fetchUser(id);
+      const m = await ctx.tryMember(id);
+      return m?.nickname ?? u.username;
+    }),
+  f('authorID', { b: 'none', d: 'ID pengirim pesan / pengguna interaksi' }, (ctx) => ctx.user?.id ?? ''),
+  f('userAvatar', { max: 2, s: '[userID?;ukuran?]', d: 'URL avatar (ukuran 16-4096)' },
+    async (ctx, [id, size]) => {
+      const u = await ctx.fetchUser(id);
+      return u.displayAvatarURL({ size: has(size) ? num(size, 'ukuran', { min: 16, max: 4096, int: true }) : 256, extension: 'png' });
+    }),
+  f('isBot', { max: 1, s: '[userID?]', d: 'true/false: apakah user adalah bot' },
+    async (ctx, [id]) => String(!!(await ctx.fetchUser(id)).bot)),
+  f('userCreatedAt', { max: 1, s: '[userID?]', d: 'Waktu akun dibuat (ms)' },
+    async (ctx, [id]) => (await ctx.fetchUser(id)).createdTimestamp),
+  f('mentioned', { b: 'required', min: 1, max: 2, s: '[nomor;fallbackAuthor?]', d: 'ID user yang di-mention ke-N (isi 2: yes = pakai pengirim bila tidak ada)' },
+    (ctx, [n, fallback]) => {
+      const i = num(n, 'nomor', { min: 1, int: true });
+      const user = ctx.mentionedUsers()[i - 1];
+      if (user) return user.id;
+      return truthy(fallback) ? (ctx.user?.id ?? '') : '';
+    }),
+  f('mention', { max: 1, s: '[userID?]', d: 'Mention user, contoh <@123>' },
+    (ctx, [id]) => `<@${has(id) ? cleanId(id) : (ctx.user?.id ?? '')}>`),
+
+  // ---- Server ---------------------------------------------------------------
+  f('serverName', { b: 'none', d: 'Nama server' }, (ctx) => ctx.requireGuild().name),
+  f('serverID', { b: 'none', d: 'ID server' }, (ctx) => ctx.requireGuild().id),
+  f('serverIcon', { b: 'none', d: 'URL ikon server' },
+    (ctx) => ctx.requireGuild().iconURL?.({ size: 256, extension: 'png' }) ?? ''),
+  f('memberCount', { b: 'none', d: 'Jumlah member server' }, (ctx) => ctx.requireGuild().memberCount),
+  f('ownerID', { b: 'none', d: 'ID pemilik server' }, (ctx) => ctx.requireGuild().ownerId),
+  f('serverCreatedAt', { b: 'none', d: 'Waktu server dibuat (ms)' }, (ctx) => ctx.requireGuild().createdTimestamp),
+  f('roleCount', { b: 'none', d: 'Jumlah role' }, (ctx) => ctx.requireGuild().roles.cache.size),
+  f('channelCount', { b: 'none', d: 'Jumlah channel' }, (ctx) => ctx.requireGuild().channels.cache.size),
+  f('channelName', { max: 1, s: '[channelID?]', d: 'Nama channel (tanpa ID = channel ini)' },
+    (ctx, [id]) => {
+      const ch = has(id) ? ctx.client.channels.cache.get(cleanId(id)) : ctx.channel;
+      if (!ch) throw new BotError(`Channel "${id}" tidak ditemukan`);
+      return ch.name ?? '';
+    }),
+  f('channelID', { b: 'none', d: 'ID channel saat ini' }, (ctx) => ctx.channel?.id ?? ''),
+  f('channelMention', { max: 1, s: '[channelID?]', d: 'Mention channel, contoh <#123>' },
+    (ctx, [id]) => `<#${has(id) ? cleanId(id) : (ctx.channel?.id ?? '')}>`),
+  f('roleName', { b: 'required', min: 1, max: 1, s: '[roleID]', d: 'Nama role' },
+    (ctx, [id]) => {
+      const role = ctx.requireGuild().roles.cache.get(cleanId(id));
+      if (!role) throw new BotError(`Role "${id}" tidak ditemukan`);
+      return role.name;
+    }),
+  f('roleMention', { b: 'required', min: 1, max: 1, s: '[roleID]', d: 'Mention role, contoh <@&123>' },
+    (ctx, [id]) => `<@&${cleanId(id)}>`),
+
+  // ---- Bot ------------------------------------------------------------------
+  f('botID', { b: 'none', d: 'ID bot' }, (ctx) => ctx.client.user.id),
+  f('botName', { b: 'none', d: 'Username bot' }, (ctx) => ctx.client.user.username),
+  f('ping', { b: 'none', d: 'Ping websocket (ms)' }, (ctx) => Math.round(ctx.client.ws.ping)),
+  f('uptime', { b: 'none', d: 'Lama bot menyala, contoh "1d 2h 3m 4s"' }, (ctx) => formatDuration(ctx.client.uptime ?? 0)),
+  f('serverCount', { b: 'none', d: 'Jumlah server tempat bot berada' }, (ctx) => ctx.client.guilds.cache.size),
+
+  // ---- Pesan / interaksi ----------------------------------------------------
+  f('message', { max: 1, s: '[nomor?]', d: 'Semua argumen setelah command, atau argumen ke-N' },
+    (ctx, [n]) => (has(n) ? (ctx.args[num(n, 'nomor', { min: 1, int: true }) - 1] ?? '') : ctx.rawArgs)),
+  f('argsCount', { b: 'none', d: 'Jumlah argumen' }, (ctx) => ctx.args.length),
+  f('messageID', { b: 'none', d: 'ID pesan / interaksi' }, (ctx) => ctx.message?.id ?? ctx.interaction?.id ?? ''),
+  f('messageContent', { b: 'none', d: 'Isi lengkap pesan pemicu' }, (ctx) => ctx.message?.content ?? ''),
+  f('commandName', { b: 'none', d: 'Nama command yang berjalan' }, (ctx) => ctx.command?.name ?? ''),
+  f('option', { b: 'required', min: 1, max: 1, s: '[nama]', d: 'Nilai opsi slash command' },
+    (ctx, [name]) => {
+      const v = ctx.options.get(name);
+      return v === undefined || v === null ? '' : String(v);
+    }),
+  f('customID', { b: 'none', d: 'customId tombol/select yang ditekan' }, (ctx) => ctx.customId ?? ''),
+  f('interactionValues', { max: 1, s: '[nomor?]', d: 'Nilai yang dipilih di select menu' },
+    (ctx, [i]) => (has(i) ? (ctx.values[num(i, 'nomor', { min: 1, int: true }) - 1] ?? '') : ctx.values.join(','))),
+  f('reactionEmoji', { b: 'none', d: 'Emoji pada event reaksi' }, (ctx) => emojiText(ctx.reaction?.emoji)),
+
+  // ---- Waktu ----------------------------------------------------------------
+  f('timestamp', { b: 'none', d: 'Waktu sekarang (ms)' }, () => String(Date.now())),
+  f('unix', { b: 'none', d: 'Waktu sekarang (detik)' }, () => String(Math.floor(Date.now() / 1000))),
+  f('date', { max: 2, s: '[format?;ms?]', d: 'Tanggal/jam. Token: YYYY MM DD HH mm ss. Zona waktu dari opsi timezone' },
+    (ctx, [format, ms]) => formatDate(
+      has(ms) ? num(ms, 'ms') : Date.now(),
+      has(format) ? format : 'YYYY-MM-DD HH:mm:ss',
+      ctx.bot.options.timezone,
+    )),
+  f('discordTime', { max: 2, s: '[ms?;gaya?]', d: 'Format waktu Discord <t:..>. Gaya: t T d D f F R' },
+    (ctx, [ms, style]) => {
+      const st = has(style) ? style : 'f';
+      if (!['t', 'T', 'd', 'D', 'f', 'F', 'R'].includes(st)) throw new BotError(`Gaya "${st}" tidak valid (t T d D f F R)`);
+      return `<t:${Math.floor((has(ms) ? num(ms, 'ms') : Date.now()) / 1000)}:${st}>`;
+    }),
+];

package/src/functions/interact.js

@@ -0,0 +1,63 @@
+'use strict';
+const { BotError } = require('../errors');
+const { f, has, truthy, num, limit } = require('./helpers');
+
+module.exports = [
+  // ---- Modal ------------------------------------------------------------------
+  f('addModal', { b: 'required', min: 2, max: 2, s: '[customID;judul]', d: 'Tampilkan form pop-up (modal). Jadi respons pertama; teks lain diabaikan. Isi dengan $addTextInput' },
+    (ctx, [id, title]) => {
+      if (ctx.modal) throw new BotError('Hanya satu modal per respons');
+      if (!id.trim() || !title.trim()) throw new BotError('customID dan judul modal tidak boleh kosong');
+      ctx.modal = { custom_id: limit('customID', id.trim(), 100), title: limit('judul', title.trim(), 45), components: [] };
+      return '';
+    }),
+  f('addTextInput', { b: 'required', min: 2, max: 8, s: '[customID;label;gaya?;placeholder?;wajib?;min?;max?;nilaiAwal?]', d: 'Tambah kolom isian ke modal (maks 5). Gaya: short / paragraph' },
+    (ctx, [id, label, style, placeholder, required, min, max, value]) => {
+      if (!ctx.modal) throw new BotError('Pakai $addModal dulu sebelum $addTextInput');
+      if (ctx.modal.components.length >= 5) throw new BotError('Maksimal 5 kolom per modal');
+      if (!id.trim() || !label.trim()) throw new BotError('customID dan label kolom tidak boleh kosong');
+      const st = has(style) ? style.trim().toLowerCase() : 'short';
+      if (!['short', 'paragraph'].includes(st)) throw new BotError(`Gaya "${style}" tidak valid (short / paragraph)`);
+      const input = {
+        type: 4,
+        custom_id: limit('customID', id.trim(), 100),
+        label: limit('label', label.trim(), 45),
+        style: st === 'short' ? 1 : 2,
+        required: has(required) ? truthy(required) : true,
+      };
+      if (has(placeholder)) input.placeholder = limit('placeholder', placeholder, 100);
+      if (has(min)) input.min_length = num(min, 'min', { min: 0, max: 4000, int: true });
+      if (has(max)) input.max_length = num(max, 'max', { min: 1, max: 4000, int: true });
+      if (input.min_length !== undefined && input.max_length !== undefined && input.min_length > input.max_length) {
+        throw new BotError('min tidak boleh lebih besar dari max');
+      }
+      if (has(value)) input.value = limit('nilai awal', value, 4000);
+      ctx.modal.components.push({ type: 1, components: [input] });
+      return '';
+    }),
+  f('modalValue', { b: 'required', min: 1, max: 1, s: '[customIDKolom]', d: 'Isi kolom modal yang dikirim pengguna (dipakai di handler bot.modal)' },
+    (ctx, [id]) => ctx.fields.get(id.trim()) ?? ''),
+
+  // ---- Autocomplete -----------------------------------------------------------
+  f('focusedValue', { b: 'none', d: 'Autocomplete: teks yang sedang diketik pengguna' }, (ctx) => ctx.focused?.value ?? ''),
+  f('focusedOption', { b: 'none', d: 'Autocomplete: nama opsi yang sedang diisi' }, (ctx) => ctx.focused?.name ?? ''),
+  f('addChoice', { b: 'required', min: 1, max: 2, s: '[nama;nilai?]', d: 'Autocomplete: tambah satu pilihan (maks 25). Nilai bawaan = nama' },
+    (ctx, [name, value]) => {
+      if (ctx.kind !== 'autocomplete') throw new BotError('$addChoice hanya untuk handler bot.autocomplete');
+      if (ctx.choices.length >= 25) throw new BotError('Maksimal 25 pilihan autocomplete');
+      if (!name.trim()) throw new BotError('Nama pilihan tidak boleh kosong');
+      ctx.choices.push({ name: limit('nama pilihan', name.trim(), 100), value: limit('nilai pilihan', has(value) ? value : name.trim(), 100) });
+      return '';
+    }),
+
+  // ---- Target (context menu & event) ----------------------------------------
+  f('targetID', { b: 'none', d: 'ID sasaran: user/pesan yang diklik kanan, atau objek event (channel/role/thread/voice/ban)' }, (ctx) => ctx.target?.id ?? ''),
+  f('targetName', { b: 'none', d: 'Nama sasaran (username / nama channel / nama role)' }, (ctx) => ctx.target?.name ?? ''),
+  f('targetContent', { b: 'none', d: 'Isi pesan yang diklik kanan (context menu pesan)' }, (ctx) => ctx.target?.content ?? ''),
+  f('messageFrom', { b: 'required', min: 1, max: 1, s: '[nomor]', d: 'Seluruh teks argumen mulai dari kata ke-N (spasi dan baris baru dipertahankan)' },
+    (ctx, [n]) => {
+      let s = ctx.rawArgs;
+      for (let i = 1; i < num(n, 'nomor', { min: 1, int: true }); i++) s = s.replace(/^\S+\s*/, '');
+      return s;
+    }),
+];