@kuvarpay/sdk 1.2.2 → 1.3.1

package/README.md

@@ -1,162 +1,129 @@
 # KuvarPay Server SDK
 
-Backend-focused SDK for creating and verifying checkout sessions, subscription sessions, invoices, and transactions using your Business SECRET API key.
+Official Node.js SDK for integrating **KuvarPay**, the ultimate fiat gateway for the crypto economy. This SDK allows you to handle checkout sessions, direct crypto-to-fiat transactions, recurring subscriptions, and split payments with ease.
 
-Works with Node 18+ (global `fetch`) or any environment where you can supply a `fetch` implementation. Also includes quick PHP cURL examples.
+[![npm version](https://badge.fury.io/js/@kuvarpay%2Fsdk.svg)](https://badge.fury.io/js/@kuvarpay%2Fsdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Installation
+## 🚀 Installation
 
-This repository includes the SDK source files. You can copy `server-sdk/index.js` (CommonJS) or `server-sdk/index.mjs` (ESM) into your backend project, or import them via your build tooling.
+```bash
+npm install @kuvarpay/sdk
+```
 
-> Requirements:
-> - Business ID
-> - SECRET API Key (server-only)
-> - Payment API Base URL (e.g., `https://pay.kuvarpay.com` or your payment host)
+## 🛠️ Quick Start (Speed Mode)
 
-## Node (CommonJS) Usage
+Initiate a payment and get a crypto deposit address in one line of code:
 
-```js
-// index.js (Node 18+)
-const { KuvarPayServer } = require('./server-sdk/index.js');
+```javascript
+const { KuvarPayServer } = require('@kuvarpay/sdk');
 
 const kv = new KuvarPayServer({
-  baseUrl: process.env.PAYMENT_API_BASE_URL, // e.g., https://pay.kuvarpay.com
-  businessId: process.env.KUVARPAY_BUSINESS_ID,
-  secretApiKey: process.env.KUVARPAY_SECRET_API_KEY,
+  businessId: 'your_business_id',
+  secretApiKey: 'rsp_secret_...' // Starts with rsp_secret_
 });
 
-async function verify(sessionId) {
-  const result = await kv.verifyPayment(sessionId);
-  console.log('Verified?', result.verified, 'status:', result.status);
+async function startPayment() {
+  const payment = await kv.createDirectPayment({
+    amount: 5000,
+    currency: 'NGN',
+    fromCurrency: 'USDT',
+    fromNetwork: 'BSC',
+    customerEmail: 'customer@example.com'
+  });
+
+  console.log('Send USDT to:', payment.depositAddress);
+  console.log('Exact amount:', payment.fromAmount); // e.g. 3.76 USDT
 }
+```
 
-async function session(sessionId) {
-  const s = await kv.getSessionStatus(sessionId);
-  console.log('Session:', s);
-}
+---
 
-async function txn(transactionId) {
-  const t = await kv.getTransactionStatus(transactionId);
-  console.log('Transaction:', t);
-}
-```
+## ⚙️ Configuration
 
-## Node (ESM) Usage
+The SDK defaults to the KuvarPay Production API (`https://payment.kuvarpay.com`).
 
-```js
-// index.mjs (Node 18+)
-import { KuvarPayServer } from './server-sdk/index.mjs';
+| Option | Description | Env Fallback |
+| :--- | :--- | :--- |
+| `businessId` | Your KuvarPay Business ID | - |
+| `secretApiKey` | Your Production Secret Key | - |
+| `baseUrl` | Overrides the API endpoint | `KUVARPAY_API_BASE_URL` |
+| `timeoutMs` | Request timeout (default 60s) | - |
 
-const kv = new KuvarPayServer({
-  baseUrl: process.env.PAYMENT_API_BASE_URL,
-  businessId: process.env.KUVARPAY_BUSINESS_ID,
-  secretApiKey: process.env.KUVARPAY_SECRET_API_KEY,
-});
+---
 
-const result = await kv.verifyPayment('sess_123');
-console.log(result);
-```
+## 📖 API Reference
 
-### Node < 18
+### 💳 Payments & Transactions
 
-Provide your own `fetchImpl` (e.g., from `node-fetch`) when constructing:
+| Method | Description |
+| :--- | :--- |
+| `createDirectPayment(data)` | **Recommended**. Creates a session & transaction in one call. |
+| `createCheckoutSession(data)` | Creates a checkout session (returns `approvalUrl`). |
+| `createTransaction(data)` | Manually initiates a crypto transaction for an existing session. |
+| `verifyPayment(sessionId)` | Convenience method to check if a payment is confirmed. |
+| `getSessionStatus(sessionId)`| Fetches full session/transaction status. |
 
-```js
-const fetch = (...args) => import('node-fetch').then(mod => mod.default(...args));
-const kv = new KuvarPayServer({ baseUrl, businessId, secretApiKey, fetchImpl: fetch });
-```
+### 📈 Subaccounts & Split Payments
 
-## PHP cURL Examples
-
-Replace `PAYMENT_API_BASE_URL`, `BUSINESS_ID`, and `SECRET_API_KEY` with your values.
-
-### Verify Payment (Checkout Session)
-
-```php
-$base = getenv('PAYMENT_API_BASE_URL');
-$businessId = getenv('KUVARPAY_BUSINESS_ID');
-$secret = getenv('KUVARPAY_SECRET_API_KEY');
-$sessionId = 'sess_123';
-
-$ch = curl_init("$base/api/v1/checkout-sessions/" . urlencode($sessionId));
-curl_setopt($ch, CURLOPT_HTTPHEADER, [
-  "Accept: application/json",
-  "X-API-Key: $secret",
-  "X-Business-ID: $businessId"
-]);
-curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
-$resp = curl_exec($ch);
-$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
-curl_close($ch);
-
-if ($statusCode >= 200 && $statusCode < 300) {
-  $data = json_decode($resp, true);
-  $status = $data['status'] ?? ($data['data']['status'] ?? null);
-  $verified = ($status === 'COMPLETED');
-  // handle $verified
-} else {
-  // handle error
-}
-```
+| Method | Description |
+| :--- | :--- |
+| `createSubaccount(data)` | Create a vendor subaccount for split settlements. |
+| `listSubaccounts()` | Fetch all subaccounts for your business. |
+| `createSplitGroup(data)` | Define percentage-based distribution between subaccounts. |
 
-### Transaction Status
-
-```php
-$transactionId = 'tx_123';
-$ch = curl_init("$base/api/v1/transactions/" . urlencode($transactionId));
-curl_setopt($ch, CURLOPT_HTTPHEADER, [
-  "Accept: application/json",
-  "X-API-Key: $secret",
-  "X-Business-ID: $businessId"
-]);
-curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
-$resp = curl_exec($ch);
-$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
-curl_close($ch);
-
-if ($statusCode >= 200 && $statusCode < 300) {
-  $data = json_decode($resp, true);
-  $status = $data['status'] ?? null;
-  // handle $status
-} else {
-  // handle error
-}
-```
+### 🔄 Subscriptions
+
+| Method | Description |
+| :--- | :--- |
+| `createDirectSubscription(data)` | Initiates a subscription setup and returns an approval URL. |
+| `renewSubscription(subId)` | Manually trigger a renewal for an active allowance. |
+| `cancelSubscription(subId)` | Hard-cancel a customer subscription. |
+| `createMeteredInvoice(subId, data)`| Charge a customer based on usage (Metered billing). |
+
+### 🏦 Banks & Verification
+
+| Method | Description |
+| :--- | :--- |
+| `getBanks(currency)` | List supported settlement banks for a specific currency. |
+| `resolveBankAccount(data)` | Verify bank account names before creating subaccounts. |
+
+---
+
+## 🔒 Security: Webhook Verification
 
-## API Reference
+Verify that incoming webhooks are genuinely from KuvarPay using HMAC-SHA256:
 
-Payments:
-- `createCheckoutSession(data)` → `{ sessionId, authToken?, approvalUrl?, raw }`
-- `getSessionStatus(sessionId)` → `{ sessionId, status, transactionId?, raw }`
-- `getTransactionStatus(transactionId)` → `{ transactionId, status, raw }`
-- `verifyPayment(sessionId)` → `{ verified: boolean, status, sessionId, transactionId?, raw }`
+```javascript
+app.post('/webhooks/kuvarpay', (req, res) => {
+  const signature = req.headers['x-kuvarpay-signature'];
+  const payload = req.body; // Raw body object
 
-Subscriptions:
-- `createSubscriptionCheckoutSession(data)` → `{ sessionId, approvalUrl?, raw }`
-- `getSubscriptionCheckoutSession(id)` → full session details
-- `confirmSubscriptionCheckoutSession(id, body?)` → confirmation response
-- `getSubscription(subscriptionId)` → full subscription details
-- `cancelSubscription(subscriptionId, body?)` → cancellation response
-- `createMeteredInvoice(subscriptionId, invoiceData)` → invoice response
-- `createSubscriptionInvoice(subscriptionId, invoiceData)` → alias to metered invoice
-- `scheduleSubscriptionInvoice(subscriptionId, invoiceData)` → enforces `chargeSchedule: 'SCHEDULED'`
-- `createRenewalCheckoutSession(body)` → renewal checkout creation
-- `renewSubscription(subscriptionId, body?)` → direct renew trigger
+  const isValid = kv.verifyWebhookSignature(payload, signature);
 
-Relay Authorization (metered):
-- `createRelayAuthorization(body)`
-- `getRelayAuthorizationStatus(body)`
-- `revokeRelayAuthorization(body)` (supports legacy path via `{ useLegacyPath: true }`)
+  if (isValid) {
+    // Process payment (e.g. status === 'completed')
+    res.status(200).send();
+  } else {
+    res.status(401).send('Invalid signature');
+  }
+});
+```
+
+---
 
-Notes:
-- Status values commonly include `PENDING`, `ARMED`, `PROCESSING`, `COMPLETED`, `FAILED`, `EXPIRED`, `CANCELLED`, etc.
-- `verifyPayment` returns `verified = true` when `status === 'COMPLETED'`.
+## 🧩 TypeScript Support
 
-## Security
+This SDK includes a full `index.d.ts` definition file. You get auto-completion and type checking out of the box.
+
+```typescript
+import { KuvarPayServer } from '@kuvarpay/sdk';
+
+const kv = new KuvarPayServer({ ... });
+```
 
-- Always keep your SECRET API key in server-side environment variables. Never expose it to the browser.
-- Use HTTPS for all API calls.
+---
 
-## Parity with Client SDK
+## 📄 License
 
-The Server SDK provides server-side equivalents of the Client SDK’s network operations (creating sessions, fetching statuses, managing subscriptions, and invoices). It does not implement browser UI features like `openPayment(...)` / `openSubscription(...)` modals, postMessage callbacks, or iframe overlays. Use the Client SDK in the browser for UI, and the Server SDK on your backend for secure API operations.
+MIT © KuvarPay Development Team

package/index.js

@@ -389,9 +389,19 @@ class KuvarPayServer {
       businessId: subscriptionData?.businessId || this.businessId,
     }, subscriptionData);
     const data = await this._post('/api/v1/subscriptions/checkout-sessions', payload);
+    const body = data.data || data.checkoutSession || data;
+    const approvalUrl = body.approvalUrl || body.approval_url || body.approvalUrl;
+    
+    // Fallback: Extract ID from approval URL if missing (e.g., .../subscriptions/ID)
+    let sessionId = body.sessionId || body.id || body.uid;
+    if (!sessionId && approvalUrl) {
+      const parts = approvalUrl.split('/');
+      sessionId = parts[parts.length - 1];
+    }
+
     return {
-      sessionId: data?.sessionId || data?.id || data?.checkoutSession?.id || data?.checkoutSession?.uid,
-      approvalUrl: data?.approvalUrl || data?.approval_url || data?.checkoutSession?.approval_url,
+      sessionId,
+      approvalUrl,
       raw: data,
     };
   }
@@ -472,10 +482,9 @@ class KuvarPayServer {
    */
   async createDirectSubscription(data) {
     const payload = Object.assign({
-      billingMode: data.billingMode || 'FIXED',
+      billingMode: data.amount ? 'METERED' : (data.billingMode || 'FIXED'),
     }, data);
 
-    // If amount/currency is provided but expectedUsage is not, map it
     if (data.amount && data.currency && !data.expectedUsage) {
       payload.expectedUsage = {
         amount: data.amount,

package/index.mjs

@@ -274,9 +274,18 @@ export class KuvarPayServer {
       businessId: subscriptionData?.businessId || this.businessId,
     }, subscriptionData);
     const data = await this._post('/api/v1/subscriptions/checkout-sessions', payload);
+    const body = data.data || data.checkoutSession || data;
+    const approvalUrl = body.approvalUrl || body.approval_url || body.approvalUrl;
+    
+    let sessionId = body.sessionId || body.id || body.uid;
+    if (!sessionId && approvalUrl) {
+      const parts = approvalUrl.split('/');
+      sessionId = parts[parts.length - 1];
+    }
+
     return {
-      sessionId: data?.sessionId || data?.id || data?.checkoutSession?.id || data?.checkoutSession?.uid,
-      approvalUrl: data?.approvalUrl || data?.approval_url || data?.checkoutSession?.approval_url,
+      sessionId,
+      approvalUrl,
       raw: data,
     };
   }
@@ -328,7 +337,7 @@ export class KuvarPayServer {
 
   async createDirectSubscription(data) {
     const payload = Object.assign({
-      billingMode: data.billingMode || 'FIXED',
+      billingMode: data.amount ? 'METERED' : (data.billingMode || 'FIXED'),
     }, data);
 
     if (data.amount && data.currency && !data.expectedUsage) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuvarpay/sdk",
-  "version": "1.2.2",
+  "version": "1.3.1",
   "description": "Official KuvarPay Server SDK for Node.js",
   "main": "index.js",
   "module": "index.mjs",