wahdx-api/README.md

Package untuk generate QRIS dan cek payment status secara realtime dengan API OrderKuota dari https://api.wahdx.co

# wahdx-api

Package untuk generate QRIS dan cek payment status secara realtime dengan API OrderKuota dari [https://api.wahdx.co](https://api.wahdx.co).

> **⚠️ PENTING: Perubahan di Versi 2.0.0**
>
> Pada versi 2.0.0, kami melakukan perubahan besar pada package ini:
> - Fitur `generateQRFromImage` telah **DIHAPUS** sepenuhnya
> - Digantikan dengan `generateQRFromAPI` yang lebih valid dan reliable
> - Dependency `sharp` dan `jsqr` telah dihapus untuk membuat package lebih ringan
>
> Jika Anda mengupgrade dari versi sebelumnya, harap perbarikan kode Anda untuk menggunakan `generateQRFromAPI` alih-alih `generateQRFromImage`.

## Fitur

- Generate kode QR dengan nominal tertentu (lokal atau via API)
- Cek status pembayaran secara realtime
- Generate bukti transaksi (receipt)
- Kompatibel di semua platform (Windows, Linux, Mac)

## Instalasi

```bash
npm install wahdx-api
```

## Konfigurasi

Buat file `.env` di root project Anda:

```
WAHDX_TOKENKEY=your_wahdx_token_key
ORKUT_TOKEN_AUTH=your_orkut_token_auth
ORKUT_USERNAME=your_orkut_username
```

> **Catatan:** Untuk mendapatkan tokenKey, Anda bisa membelinya di halaman [https://api.wahdx.co](https://api.wahdx.co)

### Opsi Konfigurasi

| Opsi                | Deskripsi                                                        | Default     |
|---------------------|------------------------------------------------------------------|-------------|
| storeName           | Nama toko yang akan ditampilkan pada receipt                     | -           |
| baseQrString        | Base QR string untuk generate QR secara lokal                    | -           |
| tokenKey            | Token key dari WAHDX                                             | -           |
| auth_token          | Token autentikasi OrderKuota                                     | -           |
| auth_username       | Username OrderKuota                                              | -           |
| autoGenerateReceipt | Mengaktifkan/menonaktifkan pembuatan receipt otomatis            | true        |

## Penggunaan

### Contoh Lengkap

```javascript
import QRISPayment from 'wahdx-api';
import '@dotenvx/dotenvx/config';
import fs from 'fs';

// Konfigurasi
const config = {
    storeName: 'AHDX STORE',
    baseQrString: 'base-qr-string-anda', // Diperlukan untuk generateQR secara lokal
    tokenKey: process.env.WAHDX_TOKENKEY, // Diperlukan untuk generateQRFromAPI
    auth_token: process.env.ORKUT_TOKEN_AUTH, // Diperlukan untuk generateQRFromAPI
    auth_username: process.env.ORKUT_USERNAME, // Diperlukan untuk generateQRFromAPI
    autoGenerateReceipt: true // Atur false jika tidak ingin otomatis membuat receipt
};

// Membuat instance QRISPayment
const qrisPayment = new QRISPayment(config);

async function main() {
    try {
        console.log('=== TEST REALTIME QRIS PAYMENT ===\n');
        const randomAmount = Math.floor(Math.random() * 99) + 1; // Random 1-99
        const amount = 100 + randomAmount; // Base 100 + random amount
        const reference = 'REF' + Date.now();
        
        // Generate QR code menggunakan API OrderKuota
        const { qrBuffer } = await qrisPayment.generateQRFromAPI(amount);
        
        // Save QR code image
        fs.writeFileSync(`qr-${amount}.png`, qrBuffer);
        
        console.log('=== TRANSACTION DETAILS ===');
        console.log('Reference:', reference);
        console.log('Amount:', amount);
        console.log('QR Image:', `qr-${amount}.png`);
        console.log('\nSilakan scan QR code dan lakukan pembayaran');
        console.log('\nMenunggu pembayaran...\n');

        // Check payment status with 5 minutes timeout
        const startTime = Date.now();
        const timeout = 5 * 60 * 1000;

        while (Date.now() - startTime < timeout) {
            const result = await qrisPayment.checkPayment(reference, amount);
            
            if (result.success && result.data.status === 'PAID') {
                console.log('✓ Pembayaran berhasil!');
                if (result.receipt) {
                    console.log('✓ Bukti transaksi:', result.receipt.filePath);
                }
                return;
            }

            await new Promise(resolve => setTimeout(resolve, 10000));   // delay 10 detik
            console.log('Menunggu pembayaran...');
        }

        throw new Error('Timeout: Pembayaran tidak diterima dalam 5 menit');
        
    } catch (error) {
        console.error('Error:', error.message);
    }
}

main();
```

### API Reference

#### Inisialisasi

```javascript
import QRISPayment from 'wahdx-api';

const config = {
    storeName: 'NAMA TOKO',
    baseQrString: 'base-qr-string-anda', // Diperlukan untuk generateQR secara lokal
    tokenKey: 'your_wahdx_token_key', // Diperlukan untuk generateQRFromAPI
    auth_token: 'your_orkut_token_auth', // Diperlukan untuk generateQRFromAPI
    auth_username: 'your_orkut_username', // Diperlukan untuk generateQRFromAPI
    autoGenerateReceipt: true // Atur false jika tidak ingin otomatis membuat receipt
};

const qrisPayment = new QRISPayment(config);
```

#### Generate QR

Ada dua metode untuk generate QR:

##### 1. Generate QR secara lokal

```javascript
const amount = 10000; // Rp 10.000
// Generate QR secara lokal menggunakan baseQrString
const { qrString, qrBuffer } = await qrisPayment.generateQR(amount);

// Simpan QR ke file
fs.writeFileSync('qr-output.png', qrBuffer);
```

##### 2. Generate QR menggunakan API OrderKuota (Lebih direkomendasikan)

```javascript
const amount = 10000; // Rp 10.000
// Generate QR menggunakan API OrderKuota
const { qrString, qrBuffer } = await qrisPayment.generateQRFromAPI(amount);

// Simpan QR ke file
fs.writeFileSync('qr-output.png', qrBuffer);
```

> **Catatan:** Metode `generateQRFromAPI` lebih direkomendasikan karena QR code dihasilkan langsung dari server OrderKuota, sehingga lebih valid dan reliable.

#### Cek Status Pembayaran

```javascript
const reference = 'REF' + Date.now();
const amount = 10000;

const result = await qrisPayment.checkPayment(reference, amount);
console.log(result);
/*
Output jika berhasil:
{
  success: true,
  data: {
    status: 'PAID',
    amount: 10000,
    reference: 'REF1234567890',
    ...
  },
  receipt: {
    filePath: 'path/to/receipt.pdf',
    ...
  }
}
*/
```

#### Generate Receipt Secara Manual

Jika Anda telah menonaktifkan `autoGenerateReceipt` dalam konfigurasi, Anda dapat menghasilkan receipt secara manual dengan metode berikut:

```javascript
// Ketika pembayaran sudah diterima
const result = await qrisPayment.checkPayment(reference, amount);

if (result.success && result.data.status === 'PAID') {
  // Generate receipt secara manual
  const receipt = await qrisPayment.generateReceipt(result.data);
  console.log('Receipt berhasil dibuat:', receipt.filePath);
}
```

## FAQ

### Q: Bagaimana cara mendapatkan tokenKey agar bisa menggunakan module ini?
A: Anda bisa membeli tokenKey di halaman utama [https://api.wahdx.co](https://api.wahdx.co)

### Q: Bagaimana cara mendapatkan kredensial API OrderKuota?
A: Silahkan kunjungi dokumentasi api [https://api.wahdx.co/api-docs](https://api.wahdx.co/api-docs) untuk mendapatkan token pada akun orderkuota anda.

### Q: Apakah module ini bisa digunakan di project CommonJS?
A: Ya! Package ini mendukung dual module system (ESM dan CommonJS). Anda bisa menggunakan dengan dua cara:

1. Dengan ES Modules (dalam file .js dengan `type: "module"` di package.json):
```javascript
import QRISPayment from 'wahdx-api';

const qrisPayment = new QRISPayment(config);
// gunakan qrisPayment
```

2. Dengan CommonJS (dalam file .cjs atau project tanpa `type: "module"`):
```javascript
const QRISPayment = require('wahdx-api');

const qrisPayment = new QRISPayment(config);
// gunakan qrisPayment
```

Package secara otomatis mendeteksi format yang digunakan dan menyediakan versi yang sesuai.

## Lisensi

MIT