npm package: @starvale-sdk/svalepay
Description: Official Node.js & TypeScript SDK for SValePay Core API (Create & Status)
Author: AltharDev
Latest version: 1.1.3

# SValePay Node.js SDK

Official SDK untuk integrasi **SValePay Core API**. Cepat, ringan (Zero Dependency), dan mendukung penuh TypeScript & JavaScript.

## 🚀 Fitur Utama
- **Core API Focus**: Hanya fitur esensial (`createPayment` & `getStatus`).
- **TypeScript Support**: Definisi tipe data lengkap untuk kenyamanan coding.
- **White Label Error**: Pesan error otomatis disesuaikan dengan brand SValePay.
- **Node.js 18+ Ready**: Menggunakan standar `fetch` modern.

---

## 📦 Instalasi

Gunakan npm atau yarn untuk menginstal:

```bash
npm install @starvale-sdk/svalepay
# atau
yarn add @starvale-sdk/svalepay
```

---

## 🛠️ Penggunaan (Usage)

### 1. Inisialisasi Client
Anda membutuhkan **Business ID** dan **Secret Key** yang bisa didapatkan dari [Dashboard Merchant SValePay](https://pay.starvale.my.id).

**JavaScript (CommonJS):**
```javascript
const { SValePay } = require('@starvale-sdk/svalepay');

const svale = new SValePay({
  businessId: 'SVP-XXXXX', // Business ID Anda
  secretKey: 'svp_live_xxxx', // Secret Key Anda
  timeout: 10000 // Opsional: default 10 detik
});
```

**TypeScript (ES Modules):**
```typescript
import { SValePay } from '@starvale-sdk/svalepay';

const svale = new SValePay({
  businessId: 'SVP-XXXXX',
  secretKey: 'svp_live_xxxx'
});
```

---

### 2. Membuat Pembayaran (Create Payment)
Gunakan fungsi ini untuk menginisialisasi transaksi baru. Jika Anda mengisi `payment_method` dengan `QRIS`, Anda akan langsung mendapatkan kode QR (QR String).

```javascript
async function handleCreatePayment() {
  try {
    const response = await svale.createPayment({
      amount: 25000,
      customer_email: 'customer@email.com',
      description: 'Pembayaran Order #123',
      payment_method: 'QRIS', // Opsional: Isi 'QRIS' untuk mendapatkan kode QR langsung
      external_id: 'ORDER-123' // ID unik dari sistem Anda (Invoice ID)
    });

    console.log('Transaction ID:', response.data.trx_id);
    console.log('Checkout URL:', response.data.checkout_url);
    
    // Jika menggunakan QRIS, gunakan payment_code untuk generate QR
    if (response.data.payment_code) {
      console.log('QRIS String:', response.data.payment_code);
    }
  } catch (error) {
    console.error('Error:', error.message);
  }
}
```

**Parameter Request (`CreatePaymentRequest`):**
| Field | Tipe | Wajib | Deskripsi |
| :--- | :--- | :--- | :--- |
| `amount` | `number` | Ya | Nominal pembayaran dalam IDR. |
| `customer_email` | `string` | Ya | Alamat email pelanggan. |
| `external_id` | `string` | Tidak | ID unik dari sistem Anda (direkomendasikan). |
| `description` | `string` | Tidak | Deskripsi transaksi. |
| `payment_method` | `string` | Tidak | Contoh: `QRIS` atau `OVO`. |
| `success_url` | `string` | Tidak | URL pengalihan saat sukses (untuk Payment Link). |

---

### 3. Cek Status Pembayaran (Check Status)
Gunakan fungsi ini untuk memverifikasi apakah pelanggan sudah membayar.

```javascript
async function checkStatus(trx_id) {
  try {
    const status = await svale.getStatus(trx_id);
    
    if (status.data.status === 'success') {
      console.log('Pembayaran Lunas!');
    } else {
      console.log('Status Saat Ini:', status.data.status); // 'pending', 'expired', dsb.
    }
  } catch (error) {
    console.error('Gagal Cek Status:', error.message);
  }
}
```

---

## 🛡️ Penanganan Error (Error Handling)
SDK ini menggunakan class `SValePayError`. Jika terjadi kesalahan pada API, pesan error akan otomatis disesuaikan agar tetap menjaga brand SValePay (White Label).

```javascript
try {
  await svale.createPayment({...});
} catch (err) {
  console.log(err.name); // 'SValePayError'
  console.log(err.code); // Kode status HTTP (401, 400, 500, dsb.)
  console.log(err.message); // Pesan error yang sudah disanitasi
}
```

---

## 📄 Lisensi
[MIT License](LICENSE) - &copy; 2024 StarVale Technology.