@akaanakbaik/pterodactyl-gateway 0.3.0

package/README.md

@@ -0,0 +1,470 @@
+# Akadev Pterodactyl Gateway
+
+SDK TypeScript dan CLI sederhana untuk membantu project Node.js terhubung ke Pterodactyl Panel dengan lebih mudah.
+
+Package ini dibuat untuk kebutuhan bot reseller panel, dashboard custom, automation server, dan admin tools. Fokus v0.2.x adalah memperluas kontrol server dengan file manager, startup variables, network allocations, database manager, backup manager, schedules, dan probe read-only, sambil tetap menjaga smart create user/server, preview, dry run, error tutorial, raw request, test, dan pack check.
+
+Package ini bukan package resmi dari Pterodactyl dan tidak berafiliasi dengan Pterodactyl Software.
+
+## Status
+
+Versi saat ini: `0.2.3`
+
+Fitur utama:
+
+- `createPtero()`
+- `createPtero.fromEnv()`
+- `connect()`
+- `health()`
+- `doctor()` dasar
+- `compatibility()` dasar
+- `raw.application` dan `raw.client`
+- `users.createSmart()`
+- `users.getOrCreate()`
+- `servers.previewCreate()`
+- `servers.createSmart()`
+- `servers.createFromPreset()`
+- `servers.createRaw()`
+- `server(identifier).start()`
+- `server(identifier).stop()`
+- `server(identifier).restart()`
+- `server(identifier).kill()`
+- `server(identifier).command()`
+- `server(identifier).resources()`
+- `server(identifier).probe()`
+- `server(identifier).files.list()`
+- `server(identifier).files.read()`
+- `server(identifier).files.write()`
+- `server(identifier).files.delete()`
+- `server(identifier).files.mkdir()`
+- `server(identifier).files.rename()`
+- `server(identifier).files.compress()`
+- `server(identifier).files.decompress()`
+- `server(identifier).files.json.read()`
+- `server(identifier).files.json.write()`
+- `server(identifier).startup.variables()`
+- `server(identifier).startup.set()`
+- `server(identifier).startup.setMany()`
+- `server(identifier).network.list()`
+- `server(identifier).network.assign()`
+- `server(identifier).network.setNote()`
+- `server(identifier).network.setPrimary()`
+- `server(identifier).network.delete()`
+- `server(identifier).databases.list()`
+- `server(identifier).databases.create()`
+- `server(identifier).databases.rotatePassword()`
+- `server(identifier).databases.delete()`
+- `server(identifier).backups.list()`
+- `server(identifier).backups.create()`
+- `server(identifier).backups.details()`
+- `server(identifier).backups.download()`
+- `server(identifier).backups.delete()`
+- `server(identifier).schedules.list()`
+- `server(identifier).schedules.create()`
+- `server(identifier).schedules.details()`
+- `server(identifier).schedules.update()`
+- `server(identifier).schedules.run()`
+- `server(identifier).schedules.delete()`
+- `server(identifier).schedules.tasks.create()`
+- `server(identifier).schedules.tasks.update()`
+- `server(identifier).schedules.tasks.delete()`
+- parser RAM, disk, CPU
+- error tutorial
+- CLI dasar `ptero-gateway`
+- `npm run verify`
+- `npm pack --dry-run`
+
+## Install lokal
+
+```bash
+npm install @akadev/pterodactyl-gateway
+```
+
+Untuk development dari GitHub:
+
+```bash
+git clone https://github.com/akaanakbaik/pterodactyl-gateway.git
+cd pterodactyl-gateway
+npm install
+npm run verify
+```
+
+## Env
+
+Buat file `.env` di project kamu:
+
+```env
+PTERO_DOMAIN=https://panel.example.com
+PTERO_PTLA=ptla_xxxxxxxxxxxxxxxxx
+PTERO_PTLC=ptlc_xxxxxxxxxxxxxxxxx
+```
+
+Penjelasan:
+
+- `PTERO_DOMAIN` adalah domain panel Pterodactyl.
+- `PTERO_PTLA` adalah Application API Key untuk aksi admin seperti create user dan create server.
+- `PTERO_PTLC` adalah Client API Key untuk kontrol server seperti start, stop, command, resources, file manager, startup variables, network allocations, database manager, backups, schedules, dan realtime pada versi berikutnya.
+
+## Koneksi cepat
+
+```ts
+import { createPtero } from "@akadev/pterodactyl-gateway";
+
+const ptero = createPtero({
+  domain: "https://panel.example.com",
+  ptla: process.env.PTERO_PTLA,
+  ptlc: process.env.PTERO_PTLC
+});
+
+const result = await ptero.connect();
+console.log(result);
+```
+
+Atau dari env:
+
+```ts
+import { createPtero } from "@akadev/pterodactyl-gateway";
+
+const ptero = createPtero.fromEnv();
+await ptero.connect();
+```
+
+## Create user smart
+
+Field wajib:
+
+- `username`
+- `email`
+- `password`
+- `administrator`
+
+Jika `firstName` dan `lastName` kosong, nilainya otomatis memakai username.
+
+```ts
+const user = await ptero.users.createSmart({
+  username: "aka",
+  email: "aka@example.com",
+  password: "auto",
+  administrator: "no"
+});
+
+console.log(user);
+```
+
+Jika `password: "auto"`, package membuat password aman dan mengembalikannya sekali pada response.
+
+## Create server smart
+
+Field wajib:
+
+- `name`
+- `email` atau `userId`
+- `description`
+- `nodeId`
+- `nestId`
+- `eggId`
+- `memory`
+- `disk`
+- `cpu`
+- `databases`
+- `allocations`
+- `backups`
+
+Yang otomatis:
+
+- docker image dari egg
+- startup command dari egg
+- environment variables dari egg
+- default allocation dari node
+- additional allocations sesuai allocation limit
+- swap default `0`
+- block IO default `500`
+- CPU pinning default kosong
+- OOM disabled default `false`
+- start on completion default `true`
+
+```ts
+const server = await ptero.servers.createSmart({
+  name: "Bot WhatsApp Aka",
+  email: "aka@example.com",
+  description: "Server bot WhatsApp untuk Aka",
+  nodeId: 1,
+  nestId: 5,
+  eggId: 15,
+  specs: {
+    memory: "2GB",
+    disk: "5GB",
+    cpu: "100%",
+    databases: 1,
+    allocations: 1,
+    backups: 1
+  }
+});
+
+console.log(server);
+```
+
+## Preview sebelum create
+
+Gunakan ini untuk melihat hasil auto-sync sebelum server benar-benar dibuat.
+
+```ts
+const preview = await ptero.servers.previewCreate({
+  name: "Bot WhatsApp Aka",
+  email: "aka@example.com",
+  description: "Server bot WhatsApp untuk Aka",
+  nodeId: 1,
+  nestId: 5,
+  eggId: 15,
+  specs: {
+    memory: "2GB",
+    disk: "5GB",
+    cpu: "100%",
+    databases: 1,
+    allocations: 1,
+    backups: 1
+  }
+});
+
+console.log(preview.payload);
+```
+
+## Probe read-only
+
+Probe dipakai untuk mengecek endpoint client server yang tersedia di panel tanpa membuat, mengedit, atau menghapus data.
+
+```ts
+const report = await ptero.server("abc12345").probe();
+console.log(report);
+```
+
+CLI:
+
+```bash
+ptero-gateway probe abc12345
+```
+
+## File manager
+
+```ts
+const server = ptero.server("abc12345");
+
+const files = await server.files.list("/");
+const text = await server.files.read("/package.json");
+await server.files.write("/index.js", "console.log('halo')");
+await server.files.mkdir("/", "logs");
+await server.files.rename("/", [{ from: "old.js", to: "new.js" }]);
+await server.files.delete("/", ["old.js"]);
+await server.files.compress("/", ["src", "package.json"]);
+await server.files.decompress("/", "archive.tar.gz");
+
+const config = await server.files.json.read("/config.json");
+await server.files.json.write("/config.json", { ok: true });
+```
+
+## Startup variables
+
+```ts
+const variables = await server.startup.variables();
+await server.startup.set("BOT_TOKEN", "token-baru");
+await server.startup.setMany({
+  NODE_ENV: "production",
+  STARTUP_FILE: "index.js"
+});
+```
+
+## Network allocations
+
+```ts
+const allocations = await server.network.list();
+await server.network.assign();
+await server.network.setNote(123, "API port");
+await server.network.setPrimary(123);
+await server.network.delete(123);
+```
+
+## Database manager
+
+```ts
+const databases = await server.databases.list();
+await server.databases.create({ database: "botdb" });
+await server.databases.create({ database: "botdb", remote: "%" });
+await server.databases.rotatePassword("database-id");
+await server.databases.delete("database-id");
+```
+
+## Backup manager
+
+```ts
+const backups = await server.backups.list();
+await server.backups.create({
+  name: "before-update",
+  ignored: ["node_modules"],
+  isLocked: false
+});
+await server.backups.details("backup-id");
+await server.backups.download("backup-id");
+await server.backups.delete("backup-id");
+```
+
+## Schedules
+
+```ts
+const schedules = await server.schedules.list();
+await server.schedules.create({
+  name: "Daily restart",
+  minute: "0",
+  hour: "3",
+  dayOfMonth: "*",
+  month: "*",
+  dayOfWeek: "*"
+});
+await server.schedules.run(1);
+await server.schedules.tasks.create(1, {
+  action: "power",
+  payload: "restart",
+  timeOffset: 0
+});
+```
+
+## Dry run
+
+`dryRun` membuat payload final tanpa mengirim request create server.
+
+```ts
+const result = await ptero.servers.createSmart(input, {
+  dryRun: true
+});
+
+console.log(result.payload);
+```
+
+## Preset paket
+
+```ts
+const ptero = createPtero({
+  domain: "https://panel.example.com",
+  ptla: process.env.PTERO_PTLA,
+  ptlc: process.env.PTERO_PTLC,
+  presets: {
+    basic: {
+      memory: "2GB",
+      disk: "5GB",
+      cpu: "100%",
+      databases: 1,
+      allocations: 1,
+      backups: 1
+    }
+  }
+});
+
+await ptero.servers.createFromPreset("basic", {
+  name: "Bot Aka",
+  email: "aka@example.com",
+  description: "Paket Basic",
+  nodeId: 1,
+  nestId: 5,
+  eggId: 15
+});
+```
+
+## Kontrol server
+
+```ts
+const server = ptero.server("abc12345");
+
+await server.start();
+await server.stop();
+await server.restart();
+await server.kill();
+await server.command("npm start");
+const resources = await server.resources();
+```
+
+Command berbahaya seperti `rm -rf /` diblokir secara default.
+
+```ts
+await server.command("rm -rf /tmp/cache", {
+  allowDangerous: true
+});
+```
+
+## Raw request
+
+Raw mode disediakan agar fitur baru atau panel fork tetap bisa dipakai.
+
+```ts
+await ptero.raw.application.get("/users");
+await ptero.raw.application.post("/servers", payload);
+await ptero.raw.client.get("/servers/abc123/resources");
+await ptero.raw.client.post("/servers/abc123/command", {
+  command: "npm start"
+});
+```
+
+## CLI dasar
+
+Setelah build atau install global:
+
+```bash
+ptero-gateway doctor
+ptero-gateway connect
+ptero-gateway ids
+ptero-gateway ids --nest 5
+ptero-gateway probe abc12345
+ptero-gateway server abc123 resources
+ptero-gateway server abc123 restart
+ptero-gateway server abc123 command "npm start"
+```
+
+## Testing di VPS Ubuntu
+
+```bash
+sudo apt update
+sudo apt install -y git curl
+curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
+sudo apt install -y nodejs
+git clone https://github.com/akaanakbaik/pterodactyl-gateway.git
+cd pterodactyl-gateway
+npm install
+npm run verify
+```
+
+`npm run verify` menjalankan:
+
+- `npm run typecheck`
+- `npm test`
+- `npm run test:cli`
+- `npm run test:pack`
+
+Jika semua berhasil, package siap dilanjutkan ke fitur versi berikutnya.
+
+## Roadmap ringkas
+
+### v0.1.x
+
+Core SDK, smart create user, smart create server, preview, dryRun, doctor dasar, CLI dasar, raw request, test, CI, pack check.
+
+### v0.2.x
+
+File manager, startup variables, database manager, backup manager, network allocations, schedules, cache, pagination, preset lebih matang.
+
+### v0.3.0
+
+WebSocket console, stats realtime, polling fallback, audit event, event emitter.
+
+### v0.4.0
+
+CLI lebih lengkap: init, create-user wizard, create-server wizard, ids, server manager.
+
+### v0.5.0
+
+TUI atau GUI CLI terminal: dashboard interaktif, preview, create server, kontrol server, console viewer.
+
+### v0.6.0
+
+Experimental nest/egg create/update/delete, import/export egg, compatibility adapter.
+
+## Lisensi
+
+MIT

package/add-promt.md

@@ -0,0 +1,192 @@
+# Add Prompt Integrasi Akadev Pterodactyl Gateway
+
+Gunakan dokumen ini sebagai prompt tambahan saat meminta AI mengintegrasikan package `@akadev/pterodactyl-gateway` ke project Node.js, bot, dashboard, atau backend API.
+
+## Prompt siap pakai
+
+Tolong integrasikan package `@akadev/pterodactyl-gateway` ke project saya dengan aman, rapi, dan mudah dipahami pemula.
+
+Package ini adalah SDK TypeScript untuk Pterodactyl Panel. Gunakan untuk koneksi panel, membuat user, membuat server, preview create server, dry run, kontrol server, dan raw request.
+
+Gunakan env berikut:
+
+```env
+PTERO_DOMAIN=https://panel.example.com
+PTERO_PTLA=isi_application_api_key
+PTERO_PTLC=isi_client_api_key
+```
+
+Jangan hardcode API key atau password di source code.
+
+## Cara koneksi
+
+```ts
+import { createPtero } from "@akadev/pterodactyl-gateway";
+
+const ptero = createPtero.fromEnv();
+await ptero.connect();
+```
+
+Atau:
+
+```ts
+const ptero = createPtero({
+  domain: process.env.PTERO_DOMAIN,
+  ptla: process.env.PTERO_PTLA,
+  ptlc: process.env.PTERO_PTLC
+});
+```
+
+## Fitur utama
+
+- `ptero.connect()` untuk cek koneksi.
+- `ptero.doctor()` untuk diagnosa konfigurasi.
+- `ptero.users.createSmart()` untuk membuat user.
+- `ptero.users.getOrCreate()` untuk mengambil user atau membuat jika belum ada.
+- `ptero.servers.previewCreate()` untuk melihat payload final sebelum create server.
+- `ptero.servers.createSmart()` untuk create server dengan auto docker image, startup, environment, default allocation, dan additional allocation.
+- `ptero.servers.createFromPreset()` untuk create server dari preset spek.
+- `ptero.server(identifier).start()` untuk start server.
+- `ptero.server(identifier).stop()` untuk stop server.
+- `ptero.server(identifier).restart()` untuk restart server.
+- `ptero.server(identifier).kill()` untuk kill server.
+- `ptero.server(identifier).command("npm start")` untuk kirim command.
+- `ptero.server(identifier).resources()` untuk mengambil resource server.
+- `ptero.raw.application` dan `ptero.raw.client` untuk endpoint yang belum tersedia wrapper.
+
+## Create user
+
+```ts
+const user = await ptero.users.createSmart({
+  username: "aka",
+  email: "aka@example.com",
+  password: "auto",
+  administrator: "no"
+});
+```
+
+Jika `password` diisi `auto`, package membuat password aman dan mengembalikannya sekali pada response.
+
+## Create server minimal
+
+```ts
+const server = await ptero.servers.createSmart({
+  name: "Bot WhatsApp Aka",
+  email: "aka@example.com",
+  description: "Server bot WhatsApp untuk Aka",
+  nodeId: 1,
+  nestId: 5,
+  eggId: 15,
+  specs: {
+    memory: "2GB",
+    disk: "5GB",
+    cpu: "100%",
+    databases: 1,
+    allocations: 1,
+    backups: 1
+  }
+});
+```
+
+## Field wajib create server
+
+- `name`
+- `email` atau `userId`
+- `description`
+- `nodeId`
+- `nestId`
+- `eggId`
+- `specs.memory`
+- `specs.disk`
+- `specs.cpu`
+- `specs.databases`
+- `specs.allocations`
+- `specs.backups`
+
+## Field otomatis create server
+
+- docker image dari egg
+- startup command dari egg
+- environment variables dari egg
+- default allocation dari node
+- additional allocations sesuai allocation limit
+- swap default `0`
+- block IO default `500`
+- CPU pinning default kosong
+- OOM disabled default `false`
+- start on completion default `true`
+
+## Preview dan dry run
+
+```ts
+const preview = await ptero.servers.previewCreate(input);
+console.log(preview.payload);
+```
+
+```ts
+const result = await ptero.servers.createSmart(input, { dryRun: true });
+console.log(result.payload);
+```
+
+## Preset paket
+
+```ts
+const ptero = createPtero({
+  domain: process.env.PTERO_DOMAIN,
+  ptla: process.env.PTERO_PTLA,
+  ptlc: process.env.PTERO_PTLC,
+  presets: {
+    basic: {
+      memory: "2GB",
+      disk: "5GB",
+      cpu: "100%",
+      databases: 1,
+      allocations: 1,
+      backups: 1
+    }
+  }
+});
+
+await ptero.servers.createFromPreset("basic", {
+  name: "Bot Aka",
+  email: "aka@example.com",
+  description: "Paket Basic",
+  nodeId: 1,
+  nestId: 5,
+  eggId: 15
+});
+```
+
+## Error handling
+
+```ts
+import { explainError } from "@akadev/pterodactyl-gateway";
+
+try {
+  await ptero.servers.createSmart(input);
+} catch (error) {
+  console.error(explainError(error));
+}
+```
+
+## Raw request
+
+```ts
+await ptero.raw.application.get("/users");
+await ptero.raw.application.post("/servers", payload);
+await ptero.raw.client.get("/servers/abc123/resources");
+await ptero.raw.client.post("/servers/abc123/command", {
+  command: "npm start"
+});
+```
+
+## Aturan integrasi
+
+- Simpan config rahasia di `.env`.
+- Jangan log API key atau password.
+- Gunakan `previewCreate()` atau `dryRun` sebelum create server final.
+- Gunakan `explainError()` untuk pesan error yang mudah dipahami.
+- Create server wajib memakai `nodeId`, `nestId`, dan `eggId` berupa angka.
+- Jika ID node, nest, atau egg salah, arahkan user untuk cek di Admin Panel Pterodactyl.
+- Jika allocation kosong, arahkan user menambah allocation di Admin Panel > Nodes > Allocations.
+- Jangan jalankan command berisiko tanpa izin jelas dari user.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}