Flow Gateway (flowgateway)

Flow Gateway (flowgateway) adalah sebuah library Node.js/TypeScript non-custodial dan developer-first yang berfungsi sebagai mesin gerbang pembayaran kripto (crypto payment gateway). Library ini didesain agar dapat diintegrasikan dengan mudah tanpa ketergantungan pada layanan SaaS pihak ketiga (zero-dependency bagi host) dan menyimpan seluruh data transaksi secara lokal menggunakan database bawaan Node.js.

Sistem ini mendukung otomatisasi pencocokan invoice menggunakan algoritma Unique Amount Matching untuk melacak invoice pada alamat dompet tunggal, serta menyajikan Dashboard Admin (berbasis Preact + Tailwind + SVG Analytics) secara langsung (bundled) melalui HTTP route handler Next.js atau Express.

✨ Fitur Utama

• Zero Host Dependencies: Memanfaatkan modul bawaan Node.js node:sqlite (sejak Node v22.5.0). Tidak memerlukan proses kompilasi native C++ yang lambat atau rentan error di server host.
• Embedded WAL Database: Konfigurasi otomatis SQLite di server lokal dengan performa Write-Ahead Logging (WAL) untuk menangani konkurensi tinggi.
• Unique Amount Matching: Logika penambahan pecahan desimal unik (misalnya $150 dikonversi menjadi 150.00132 USDT) untuk mencocokkan pembayaran pembayar secara deterministik tanpa perlu mengganti alamat dompet target.
• Resilient Rate Fetcher: Mengambil kurs secara langsung dari Binance API, lengkap dengan sistem caching 1 jam di database SQLite lokal dan fallback offline otomatis jika API eksternal mengalami gangguan.
• Built-in Cyberpunk Dashboard: Dashboard analitik terintegrasi berbasis Preact + Tailwind CSS (Vite SPA) dengan skema warna gelap (#101010) dan aksen hijau neon (#D5ED3A). Menyediakan:
  • KPI Cards: Total Pendapatan, Success Rate, Invoice Berjalan, dan Terbayar.
  • Interactive SVG Chart: Volume transaksi harian selama 14 hari terakhir tanpa dependensi pustaka chart pihak ketiga.
  • Data Grid & Search: Log data transaksi lengkap beserta filter, tombol salin instan, dan tautan blockchain explorer.
  • Payment Simulator: Tombol untuk mensimulasikan pembayaran on-chain langsung dari dashboard pada mode development.
• Secured Auth: Autentikasi dashboard terlindungi menggunakan token JWT stateless berbasis enkripsi bawaan crypto HMAC-SHA256 yang divalidasi terhadap FLOW_ADMIN_SECRET.

📁 Struktur Direktori

flowgateway/
├── dist/                      # Output kompilasi library utama (.js, .cjs, .d.ts)
├── dist-admin/                # Output kompilasi aset statis Dashboard (Vite SPA)
├── src/                       # Source Code Node.js Engine
│   ├── index.ts               # Ekspor kelas utama FlowGateway
│   ├── database/
│   │   ├── schema.sql         # Definisi tabel SQLite
│   │   └── client.ts          # Inisialisasi node:sqlite dengan mode WAL
│   ├── core/
│   │   ├── engine.ts          # Logika createInvoice, getInvoice, dan sync
│   │   ├── unique-amount.ts   # Algoritma pencocokan pecahan desimal unik
│   │   ├── rate-fetcher.ts    # Fetcher nilai kurs Binance + SQLite Cache
│   │   └── auth.ts            # Helper stateless JWT dengan HMAC-SHA256
│   └── handlers/
│       ├── next.ts            # Handler untuk Next.js App Router (UI & API)
│       └── express.ts         # Middleware untuk Express.js
└── dashboard/                 # Source Code Preact Dashboard SPA

⚙️ Persyaratan Sistem

• Node.js: Versi v22.5.0 atau yang lebih baru (karena memerlukan modul bawaan node:sqlite).

📦 Instalasi

Tambahkan package ke project Anda:

npm install flowgateway

🛠️ Panduan Integrasi

1. Inisialisasi Gateway (lib/flow.ts)

Buat sebuah instance FlowGateway yang dibagikan ke seluruh aplikasi Anda.

import { FlowGateway } from 'flowgateway';

export const flow = new FlowGateway({
  dbPath: './data/flow.db', // Lokasi file database SQLite lokal
  chains: {
    TRC20: { 
      enabled: true, 
      targetAddress: process.env.TRX_WALLET_ADDRESS || 'TUSDT_TARGET_ADDRESS_TRON' 
    },
    ERC20: { 
      enabled: true, 
      targetAddress: process.env.ETH_WALLET_ADDRESS || '0xUSDT_TARGET_ADDRESS_ETH' 
    },
    BTC: { 
      enabled: false, 
      targetAddress: '1BTC_TARGET_ADDRESS' 
    }
  },
  admin: {
    secret: process.env.FLOW_ADMIN_SECRET || 'supersecretpasscode', // Kata sandi dashboard
    basePath: '/api/flow' // Base URL endpoint API & Dashboard
  }
});

2. Pemasangan Handler

A. Next.js App Router (app/api/flow/[[...route]]/route.ts)

Untuk Next.js, pasang gateway handler di route dinamis App Router:

import { flow } from '@/lib/flow';

const handler = flow.NextHandler();

export { handler as GET, handler as POST };

Akses dashboard admin Anda secara langsung melalui browser di: http://localhost:3000/api/flow

B. Express.js Server (server.js)

Untuk Express, pasang sebagai middleware router:

import express from 'express';
import { flow } from './lib/flow.js';

const app = express();

// Middleware JSON parser wajib dipasang untuk memproses body permintaan POST
app.use(express.json());

// Pasang middleware Express FlowGateway
app.use(flow.ExpressHandler());

app.listen(3000, () => {
  console.log('Server berjalan di port 3000');
});

Akses dashboard admin Anda secara langsung di: http://localhost:3000/api/flow

💻 Cara Penggunaan (API Utama)

Membuat Invoice Baru

Untuk membuat pembayaran baru (misalnya setelah pengguna melakukan checkout):

const invoice = await flow.createInvoice({
  amount: 150.00, // Jumlah tagihan dalam USD/EUR
  currency: 'USD',
  expiresMinutes: 30, // Waktu kedaluwarsa invoice (default: 30 menit)
  metadata: { 
    orderId: 'ORDER-8821', 
    customerEmail: '[email protected]' 
  }
});

console.log(invoice);

Contoh Output Respons:

{
  "id": "inv_2b83521bf5",
  "baseAmount": 150.00,
  "baseCurrency": "USD",
  "status": "PENDING",
  "createdAt": "2026-07-08T11:00:00.000Z",
  "expiresAt": "2026-07-08T11:30:00.000Z",
  "paymentOptions": [
    {
      "id": "opt_a1b2c3d4",
      "invoiceId": "inv_2b83521bf5",
      "chain": "TRC20",
      "currency": "USDT",
      "targetAddress": "TUSDT_TARGET_ADDRESS_TRON",
      "requiredAmount": 150.00132, 
      "amountReceived": 0,
      "status": "PENDING"
    },
    {
      "id": "opt_e5f6g7h8",
      "invoiceId": "inv_2b83521bf5",
      "chain": "ERC20",
      "currency": "USDT",
      "targetAddress": "0xUSDT_TARGET_ADDRESS_ETH",
      "requiredAmount": 150.00412,
      "amountReceived": 0,
      "status": "PENDING"
    }
  ]
}

Catatan: Pembayar hanya perlu membayar salah satu dari opsi paymentOptions tersebut dengan jumlah requiredAmount yang persis sama.

Mendapatkan Status Invoice

Gunakan getInvoice untuk memeriksa status terbaru transaksi:

const invoice = flow.getInvoice("inv_2b83521bf5");
console.log(invoice?.status); // 'PENDING' | 'PAID' | 'EXPIRED'

Sinkronisasi Transaksi On-Chain

Anda dapat memicu sinkronisasi transaksi secara manual atau menggunakan server cron job untuk memeriksa transaksi masuk dari public explorers (Tronscan, Blockscout, Blockstream):

const result = await flow.syncPendingInvoices();
console.log(`Berhasil memperbarui ${result.updatedCount} transaksi.`);

🛠️ Pengembangan Kontributor

Jika Anda ingin berkontribusi atau melakukan pengujian secara lokal:

1. Clone repositori ini.
2. Jalankan perintah instalasi pada root dan subfolder dashboard:

   npm install
   npm install --prefix dashboard

3. Lakukan build penuh untuk dashboard UI dan core library:

   npm run build

4. Jalankan script pengujian integrasi lokal:

   npm run test