@akaanakbaik/pterodactyl-gateway 1.0.0 → 1.0.2

package/README.md

@@ -1,23 +1,79 @@
 # Akadev Pterodactyl Gateway
 
-SDK TypeScript dan CLI untuk mengelola Pterodactyl Panel dengan lebih cepat, aman, dan nyaman dari Node.js maupun terminal.
+<p align="center">
+  <b>SDK TypeScript + CLI modern untuk mengelola Pterodactyl Panel dari bot, dashboard, backend, website, dan terminal.</b>
+</p>
 
-Package ini cocok untuk bot reseller panel, dashboard custom, automation server, admin tools, dan project yang perlu membuat user/server Pterodactyl secara otomatis.
+<p align="center">
+  <code>@akaanakbaik/pterodactyl-gateway</code> · <code>v1.0.2</code> · <code>Node.js &gt;=18</code> · <code>MIT</code>
+</p>
+
+<p align="center">
+  <a href="https://web-docs-pterodacty-gateway.vercel.app"><b>Web Docs</b></a>
+  ·
+  <a href="https://www.npmjs.com/package/@akaanakbaik/pterodactyl-gateway"><b>npm</b></a>
+  ·
+  <a href="https://github.com/akaanakbaik/pterodactyl-gateway"><b>GitHub</b></a>
+</p>
+
+Akadev Pterodactyl Gateway membantu kamu menghubungkan aplikasi Node.js ke Pterodactyl Panel dengan flow yang lebih aman, cepat, dan mudah diuji: cek koneksi, membuat user, membuat server, dry-run payload, mengelola file, startup variables, backups, schedules, power action, sampai helper integrasi bot/website.
 
 > Package ini bukan package resmi dari Pterodactyl dan tidak berafiliasi dengan Pterodactyl Software.
 
-## Status
+## Web Docs
 
-Versi saat ini: `1.0.0`
+Dokumentasi lengkap versi web tersedia di:
 
-- npm package: `@akaanakbaik/pterodactyl-gateway`
-- CLI utama: `ptero-gateway` dan `ptg`
-- CLI wizard: `ptero-wizard`
-- Runtime: Node.js `>=18`
-- License: MIT
+```txt
+https://web-docs-pterodacty-gateway.vercel.app
+```
+
+Web docs berisi tutorial per halaman/path agar mudah dipahami pemula:
+
+```txt
+/docs/overview
+/docs/install
+/docs/config
+/docs/cli-create-server
+/docs/sdk
+/docs/integrations/telegram-bot
+/docs/integrations/whatsapp-bot
+/docs/integrations/discord-bot
+/docs/integrations/website-api
+/docs/security
+/docs/troubleshooting
+/privacy
+/terms
+```
+
+Fitur web docs:
+
+- Search lokal cepat.
+- Floating AI assistant untuk pertanyaan seputar gateway.
+- Tutorial step-by-step.
+- Simulasi animasi penggunaan.
+- Contoh integrasi Telegram bot, WhatsApp bot, Discord bot, website/API, SDK, CLI, dan troubleshooting.
+- Privacy Policy dan Terms.
+- SEO lengkap: sitemap, robots, canonical, OpenGraph, Twitter card, JSON-LD, manifest, dan SVG icon.
+
+## Navigasi
+
+- [Install](#install)
+- [Quick start CLI](#quick-start-cli)
+- [SDK usage](#sdk-usage)
+- [Environment](#environment)
+- [CLI reference](#cli-reference)
+- [Preset dan template](#preset-dan-template)
+- [Integration helpers](#integration-helpers)
+- [Contoh integrasi](#contoh-integrasi)
+- [Keamanan](#keamanan)
+- [Troubleshooting](#troubleshooting)
+- [Release dan testing](#release-dan-testing)
 
 ## Install
 
+Install sebagai dependency project:
+
 ```bash
 npm i @akaanakbaik/pterodactyl-gateway
 ```
@@ -28,7 +84,7 @@ Install global CLI:
 npm i -g @akaanakbaik/pterodactyl-gateway
 ```
 
-Cek versi dan kondisi package:
+Cek instalasi:
 
 ```bash
 ptero-gateway version
@@ -36,25 +92,7 @@ ptero-gateway self-check
 ptero-gateway release-check
 ```
 
-## API key
-
-Gunakan dua jenis key sesuai kebutuhan:
-
-```env
-PTERO_DOMAIN=https://panel.example.com
-PTERO_PTLA=ptla_xxxxxxxxxxxxxxxxx
-PTERO_PTLC=ptlc_xxxxxxxxxxxxxxxxx
-```
-
-- `PTERO_DOMAIN`: domain panel Pterodactyl.
-- `PTERO_PTLA`: Application API Key untuk aksi admin seperti list user, create user, create server, update limits, suspend, unsuspend, dan reinstall.
-- `PTERO_PTLC`: Client API Key untuk kontrol server seperti resources, file manager, startup variables, ports, backups, schedules, dan power action.
-
-Jangan hardcode API key ke source code.
-
-## Config profile
-
-Sejak `0.8.0`, CLI bisa menyimpan profile lokal agar tidak perlu export env berulang-ulang.
+## Quick start CLI
 
 ```bash
 ptero-gateway config init \
@@ -63,106 +101,20 @@ ptero-gateway config init \
   --ptla ptla_xxx \
   --ptlc ptlc_xxx
 
-ptero-gateway config doctor
-ptero-gateway config list
-ptero-gateway doctor
-```
-
-File config disimpan di:
-
-```txt
-~/.pterodactyl-gateway/config.json
-```
-
-File tersebut berisi API key dan otomatis diberi permission `600`.
-
-Command config:
-
-```bash
-ptero-gateway config path
-ptero-gateway config init --profile main --domain https://panel.example.com --ptla ptla_xxx --ptlc ptlc_xxx
-ptero-gateway config list
-ptero-gateway config show main
-ptero-gateway config use main
-ptero-gateway config rename main production
-ptero-gateway config delete production --yes
-ptero-gateway config env main
-ptero-gateway config doctor
-```
-
-## CLI cepat
-
-```bash
-ptero-gateway help
 ptero-gateway doctor
-ptero-gateway connect
-ptero-gateway ids
 ptero-gateway ids --nest 5
-ptero-gateway servers
-```
-
-List admin:
-
-```bash
 ptero-gateway admin users
 ptero-gateway admin servers
+ptero-gateway servers
 ```
 
-## Preset server
-
-```bash
-ptero-gateway presets
-```
-
-Preset bawaan:
-
-| Preset | Memory | Disk | CPU | Database | Allocation | Backup |
-|---|---:|---:|---:|---:|---:|---:|
-| mini | 512MB | 1GB | 50% | 0 | 1 | 0 |
-| basic | 1GB | 2GB | 100% | 0 | 1 | 0 |
-| standard | 2GB | 5GB | 200% | 1 | 1 | 1 |
-| premium | 4GB | 10GB | 300% | 2 | 2 | 2 |
-| unlimited | 0 | 0 | 0 | 5 | 3 | 3 |
-
-Nilai preset tetap bisa dioverride dengan `--memory`, `--disk`, `--cpu`, `--databases`, `--allocations`, dan `--backups`.
-
-## Templates
-
-Template hanya membuat rekomendasi command create-server. Template tidak membuat node, location, atau allocation.
-
-```bash
-ptero-gateway templates list
-ptero-gateway templates show nodejs-bot
-ptero-gateway templates command nodejs-bot --name "bot saya" --email user@example.com --node 1 --nest 5 --egg 18
-```
-
-Template bawaan:
-
-- `nodejs-bot`
-- `nodejs-api`
-- `wa-bot`
-- `python-bot`
-- `blank`
-
-## Create user
-
-```bash
-ptero-gateway admin create-user \
-  --username aka_test \
-  --email user@example.com \
-  --password "password aman" \
-  --yes
-```
-
-## Create server
-
-Selalu mulai dengan dry-run:
+Create server dengan dry-run:
 
 ```bash
 ptero-gateway admin create-server \
   --name "aka test" \
-  --email "user@example.com" \
-  --username "aka_test" \
+  --email user@example.com \
+  --username aka_test \
   --password "password aman" \
   --node 1 \
   --nest 5 \
@@ -171,13 +123,13 @@ ptero-gateway admin create-server \
   --dry-run
 ```
 
-Jika payload sudah benar, eksekusi asli:
+Create server asli:
 
 ```bash
 ptero-gateway admin create-server \
   --name "aka test" \
-  --email "user@example.com" \
-  --username "aka_test" \
+  --email user@example.com \
+  --username aka_test \
   --password "password aman" \
   --node 1 \
   --nest 5 \
@@ -186,22 +138,95 @@ ptero-gateway admin create-server \
   --yes
 ```
 
-## Wizard
+## SDK usage
 
-Wizard membantu input secara interaktif tanpa membuka kontrol node/location/allocation.
+```ts
+import { createPtero } from "@akaanakbaik/pterodactyl-gateway";
 
-```bash
-ptero-wizard help
-ptero-wizard create-user --dry-run
-ptero-wizard create-server --dry-run
-ptero-wizard create-server --yes
+const ptero = createPtero.fromEnv();
+const doctor = await ptero.doctor();
+console.log(doctor);
+```
+
+Create server dari SDK:
+
+```ts
+const server = await ptero.servers.createSmart({
+  name: "Bot User",
+  email: "user@example.com",
+  username: "user_bot",
+  password: "auto",
+  autoCreateUser: true,
+  description: "Server bot user",
+  nodeId: 1,
+  nestId: 5,
+  eggId: 18,
+  specs: {
+    memory: "1GB",
+    disk: "2GB",
+    cpu: "100%",
+    databases: 0,
+    allocations: 1,
+    backups: 0
+  }
+});
 ```
 
-Node ID, Nest ID, dan Egg ID tetap diisi manual oleh admin. Gunakan `ptero-gateway ids` untuk melihat daftar ID.
+Client server handle:
+
+```ts
+const serverHandle = ptero.server("311d56b7");
+
+await serverHandle.resources();
+await serverHandle.files.list("/");
+await serverHandle.files.write("/tmp/hello.txt", "halo");
+await serverHandle.startup.set("CMD_RUN", "node index.js");
+await serverHandle.start();
+```
+
+## Environment
+
+Gunakan environment variable untuk deployment:
+
+```env
+PTERO_DOMAIN=https://panel.example.com
+PTERO_PTLA=ptla_xxxxxxxxxxxxxxxxx
+PTERO_PTLC=ptlc_xxxxxxxxxxxxxxxxx
+```
+
+| Env | Fungsi |
+|---|---|
+| `PTERO_DOMAIN` | Domain panel Pterodactyl. |
+| `PTERO_PTLA` | Application API Key untuk aksi admin seperti user, server, suspend, limits. |
+| `PTERO_PTLC` | Client API Key untuk kontrol server, file manager, backups, schedules, resources. |
+
+Tips:
+
+- PTLA hanya untuk backend/admin service.
+- PTLC hanya untuk fitur client server yang diperlukan.
+- Jangan hardcode key ke source code, repo, frontend, pesan bot, atau log publik.
+- Pisahkan key development dan production.
+
+## CLI reference
+
+Health dan info:
+
+```bash
+ptero-gateway help
+ptero-gateway version
+ptero-gateway self-check
+ptero-gateway release-check
+ptero-gateway doctor
+ptero-gateway connect
+ptero-gateway ids
+ptero-gateway ids --nest 5
+```
 
-## Admin server
+Admin:
 
 ```bash
+ptero-gateway admin users
+ptero-gateway admin servers
 ptero-gateway admin server 5 detail
 ptero-gateway admin server 5 limits
 ptero-gateway admin server 5 update-limits --backups 1 --yes
@@ -210,7 +235,7 @@ ptero-gateway admin server 5 unsuspend --yes
 ptero-gateway admin server 5 reinstall --yes
 ```
 
-## Client server
+Client server:
 
 ```bash
 ptero-gateway probe 311d56b7
@@ -225,14 +250,7 @@ ptero-gateway server 311d56b7 backups
 ptero-gateway server 311d56b7 schedules
 ```
 
-Write file:
-
-```bash
-ptero-gateway server 311d56b7 write /tmp/test.txt "halo" --yes
-ptero-gateway server 311d56b7 write /index.js "console.log('halo')" --yes --allow-any-path
-```
-
-Power action:
+Power dan command:
 
 ```bash
 ptero-gateway server 311d56b7 start --yes
@@ -242,122 +260,167 @@ ptero-gateway server 311d56b7 kill --yes
 ptero-gateway server 311d56b7 command "npm start" --yes
 ```
 
-Template Node alive:
+## Preset dan template
 
 ```bash
-ptero-gateway server 311d56b7 stop --yes
-ptero-gateway server 311d56b7 init-node-alive --yes
-ptero-gateway server 311d56b7 start --yes
+ptero-gateway presets
+ptero-gateway templates list
+ptero-gateway templates show nodejs-bot
+ptero-gateway templates command nodejs-bot --name "bot saya" --email user@example.com --node 1 --nest 5 --egg 18
 ```
 
-Backup:
+Preset bawaan:
+
+| Preset | Cocok untuk |
+|---|---|
+| `mini` | Testing dan bot kecil. |
+| `basic` | Bot Telegram/Discord sederhana. |
+| `standard` | Bot WhatsApp, API, website kecil. |
+| `premium` | Project lebih aktif. |
+| `unlimited` | Resource unlimited sesuai aturan panel. |
 
-```bash
-ptero-gateway server 311d56b7 backups
-ptero-gateway server 311d56b7 create-backup --name "before-update" --yes
-ptero-gateway server 311d56b7 backup <uuid>
-ptero-gateway server 311d56b7 delete-backup <uuid> --yes
+Template bawaan:
+
+```txt
+nodejs-bot
+nodejs-api
+wa-bot
+python-bot
+blank
 ```
 
-## SDK
+## Integration helpers
+
+Helper integrasi membuat input server lebih konsisten untuk bot dan website.
 
 ```ts
-import { createPtero } from "@akaanakbaik/pterodactyl-gateway";
+import { createIntegrationService } from "@akaanakbaik/pterodactyl-gateway";
 
-const ptero = createPtero({
-  domain: "https://panel.example.com",
+const service = createIntegrationService({
+  domain: process.env.PTERO_DOMAIN,
   ptla: process.env.PTERO_PTLA,
   ptlc: process.env.PTERO_PTLC
+}, {
+  nodeId: 1,
+  nestId: 5,
+  eggId: 18,
+  preset: "standard",
+  autoCreateUser: true
 });
 
-await ptero.connect();
+const dryRun = await service.dryRun({
+  kind: "telegram-bot",
+  name: "Telegram Bot User",
+  email: "user@example.com",
+  username: "user_tg",
+  password: "auto"
+});
 ```
 
-Dari env:
+Kind yang tersedia:
 
 ```ts
-import { createPtero } from "@akaanakbaik/pterodactyl-gateway";
-
-const ptero = createPtero.fromEnv();
-const doctor = await ptero.doctor();
-console.log(doctor);
+"whatsapp-bot" | "telegram-bot" | "discord-bot" | "nodejs-api" | "website" | "python-bot" | "blank"
 ```
 
-Create user SDK:
+## Contoh integrasi
+
+Telegram bot:
 
 ```ts
-const user = await ptero.users.createSmart({
-  username: "aka_test",
-  email: "user@example.com",
-  password: "auto",
-  administrator: false
+const result = await service.create({
+  kind: "telegram-bot",
+  name: `tg-${ctx.from.id}`,
+  email: `${ctx.from.id}@telegram.local`,
+  username: `tg_${ctx.from.id}`,
+  password: "auto"
 });
 ```
 
-Create server SDK:
+WhatsApp bot:
 
 ```ts
-const server = await ptero.servers.createSmart({
-  name: "Bot WhatsApp Aka",
-  email: "user@example.com",
-  username: "aka_test",
-  password: "password aman",
-  autoCreateUser: true,
-  description: "Server bot WhatsApp",
-  nodeId: 1,
-  nestId: 5,
-  eggId: 18,
-  specs: {
-    memory: "1GB",
-    disk: "2GB",
-    cpu: "100%",
-    databases: 0,
-    allocations: 1,
-    backups: 0
+const result = await service.create({
+  kind: "whatsapp-bot",
+  name: `wa-${order.username}`,
+  email: order.email,
+  username: order.username,
+  password: "auto",
+  environment: {
+    OWNER_NUMBER: order.phone,
+    BOT_NAME: order.botName
   }
 });
 ```
 
-Dry-run SDK:
+Website/API:
 
 ```ts
-const preview = await ptero.servers.createSmart(input, { dryRun: true });
-console.log(preview.payload);
+app.post("/api/panel/create", async (req, res) => {
+  const paid = await checkPayment(req.body.orderId);
+  if (!paid) return res.status(403).json({ ok: false, error: "Belum dibayar" });
+
+  const result = await service.create({
+    kind: "website",
+    name: req.body.name,
+    email: req.body.email,
+    username: req.body.username,
+    password: "auto"
+  });
+
+  res.json({ ok: true, result });
+});
 ```
 
-Client SDK:
+Dokumentasi contoh lengkap ada di web docs:
 
-```ts
-const server = ptero.server("311d56b7");
-
-await server.resources();
-await server.files.list("/");
-await server.files.read("/package.json");
-await server.files.write("/tmp/test.txt", "halo");
-await server.startup.variables();
-await server.startup.set("CMD_RUN", "node index.js");
-await server.backups.list();
+```txt
+https://web-docs-pterodacty-gateway.vercel.app/docs/integrations/telegram-bot
+https://web-docs-pterodacty-gateway.vercel.app/docs/integrations/whatsapp-bot
+https://web-docs-pterodacty-gateway.vercel.app/docs/integrations/discord-bot
+https://web-docs-pterodacty-gateway.vercel.app/docs/integrations/website-api
 ```
 
-Raw request:
+## Keamanan
 
-```ts
-await ptero.raw.application.get("/users");
-await ptero.raw.client.get("/servers/311d56b7/resources");
+- Jangan hardcode PTLA/PTLC.
+- Jangan kirim API key atau config profile ke user.
+- Jangan log password generated ke public log.
+- Semua aksi tulis/ubah via CLI wajib `--yes`.
+- Write file CLI default hanya boleh ke `/tmp`; path lain wajib `--allow-any-path`.
+- Command berbahaya diblokir oleh guard command.
+- Delete user/server permanen tidak dibuka di CLI stabil.
+- Command node/location/allocation management tidak dibuka di CLI stabil.
+- Frontend tidak boleh memegang API key panel. Gunakan backend untuk semua aksi create server.
+
+## Troubleshooting
+
+```bash
+ptero-gateway explain DOMAIN_REQUIRED
+ptero-gateway explain DOCKER_IMAGE_NOT_FOUND
+ptero-gateway explain STARTUP_VARIABLE_NOT_FOUND
+ptero-gateway explain EEXIST
 ```
 
-## Keamanan
+Masalah umum:
 
-- Jangan hardcode PTLA/PTLC di source code.
-- Config lokal berisi API key; jangan upload `~/.pterodactyl-gateway/config.json`.
-- Semua aksi tulis/ubah via CLI wajib `--yes`.
-- Write file CLI default hanya boleh ke `/tmp`; untuk path lain wajib `--allow-any-path`.
-- Command berbahaya seperti `rm -rf /` diblokir oleh guard command.
-- Gunakan `--dry-run` sebelum create server asli.
-- Command node/location/allocation management sengaja tidak dibuka.
-- Delete user/server permanen sengaja tidak dibuka di CLI stabil.
+| Masalah | Solusi |
+|---|---|
+| `DOMAIN_REQUIRED` | Isi `PTERO_DOMAIN` atau jalankan `ptero-gateway config init`. |
+| PTLA tidak valid | Buat ulang Application API Key dan pastikan permission cukup. |
+| PTLC tidak valid | Buat ulang Client API Key dari account panel. |
+| Docker image tidak ditemukan | Cek egg Docker Images atau isi `--docker-image`. |
+| Tidak ada allocation kosong | Tambahkan allocation dari panel admin node. |
+| Backup gagal limit 0 | Naikkan limit backup server dulu. |
+| Binary global konflik | Hapus `/usr/bin/ptero-gateway`, `/usr/bin/ptg`, lalu install ulang. |
+
+Tutorial lengkap troubleshooting:
+
+```txt
+https://web-docs-pterodacty-gateway.vercel.app/docs/troubleshooting
+```
 
-## Testing lokal
+## Release dan testing
 
 ```bash
 git clone https://github.com/akaanakbaik/pterodactyl-gateway.git
@@ -366,22 +429,27 @@ npm install
 npm run verify
 ```
 
-`npm run verify` menjalankan typecheck, unit test, CLI smoke test, release guard, dan pack dry-run.
-
-## Release checklist
+Checklist publish:
 
 ```bash
 npm run verify
 npm publish --access public
-npm view @akaanakbaik/pterodactyl-gateway@1.0.0 version --prefer-online --registry=https://registry.npmjs.org/
-npm i -g @akaanakbaik/pterodactyl-gateway@1.0.0 --force --prefer-online --registry=https://registry.npmjs.org/
+npm view @akaanakbaik/pterodactyl-gateway@1.0.2 version --prefer-online --registry=https://registry.npmjs.org/
+npm i -g @akaanakbaik/pterodactyl-gateway@1.0.2 --force --prefer-online --registry=https://registry.npmjs.org/
 ptero-gateway self-check
 ptero-gateway release-check
+ptero-gateway doctor
 ```
 
-## Menuju 1.0.0
+## Versi npm lama
+
+Rilis utama yang direkomendasikan adalah `1.0.2` atau `latest`. Versi lama tidak dipromosikan lagi di dokumentasi.
 
-`0.9.1` adalah hardening patch release sebelum stabil. Fokus berikutnya untuk `1.0.0` adalah stabilisasi API, dokumentasi final, dan kompatibilitas panel/fork yang lebih luas.
+Contoh deprecate versi lama:
+
+```bash
+npm deprecate @akaanakbaik/pterodactyl-gateway@"<1.0.0" "Versi lama tidak direkomendasikan. Gunakan @akaanakbaik/pterodactyl-gateway@latest."
+```
 
 ## Lisensi