@rkfl/transact-server 2.1.1-alpha.0 → 2.2.0-alpha.0

package/README.md

@@ -1,347 +1,347 @@
-# Rocketfuel SDK (Node.js)
-
-A secure and minimal Node.js SDK to interact with Rocketfuel payment APIs. (This SDK is for Node.js server-side usage.)
-
-## Installation
-
-```bash
-npm i @rkfl/transact-server
-```
-## Documentation
-Click here for more detailed [Documentation](https://docs.rocketfuel.inc/plug-ins-and-sdks/javascript-js/rocketfuel-sdk-nodejs)
-## Usage
-
-### Create order
-
-```ts
-import { Rocketfuel } from '@rocketfuel/plugin';
-
-const client = new Rocketfuel({
-  clientId: 'YOUR_ID',
-  clientSecret: 'YOUR_SECRET',
-  merchantId: 'YOUR_MERCHANT_ID',
-  domain: 'production' // or 'sandbox'
-});
-
-const orderData = {
-  amount: "10",
-  currency: "USD",
-  cart: [
-    {
-      id: "iphone_14_pro_max",
-      name: "iPhone 14 Pro Max",
-      price: "10",
-      quantity: 1
-    }
-  ],
-  customerInfo: {
-    name: "John Doe",
-    email: "john.doe@example.com"
-  },
-  customParameter: {
-    returnMethod: "GET",
-    params: [
-      {
-        name: "submerchant",
-        value: "mobilesale"
-      }
-    ]
-  },
-  merchant_id: '14ec584d-53af-476d-aacd-2b7f025cf21b'
-};
-
-const result = await client.createOrder(orderData);
-
-```
-
-### Transaction Lookup
-To check or confirm the transaction status using order id or Rocketfuel provided transaction id
-
-```
-
-async function checkTransaction(txId) {
-  try {
-    const result = await client.transactionLookup(txId, 'ORDERID');
-    console.log('Transaction Details:', result);
-    // Process the transaction details as needed
-  } catch (error) {
-    console.error('Error fetching transaction details:', error.message);
-  }
-}
-​
-// Example call:
-checkTransaction('12345ABC');
-```
-
-### Webook Verification
-Use this function to verify that a webhook is valid and trusted before processing its contents. It prevents spoofed requests, data tampering, and unauthorized events.
-This function returns true if the signature is valid, otherwise false.
-
-```ts
-function handleWebhook(req, res) {
-  const isValid = client.verifyWebhookSignature(req.body);
-
-  if (!isValid) {
-    console.warn('Webhook signature verification failed');
-    return res.status(403).send('Invalid signature');
-  }
-
-  const payload = JSON.parse(req.body.data.data);
-  console.log('Verified Webhook Payload:', payload);
-
-  // Process your payload
-  res.status(200).send('Webhook received');
-}
-```
-
-## Payouts SDK (Fiat, Crypto & Admin)
-
-The payouts SDK lets you invite payees, manage KYC, allocate/administer balances, and send fiat or crypto payouts using a single high-level client.
-
-### Payout client setup
-
-```ts
-import { RocketfuelPayouts } from '@rkfl/transact-server';
-
-const payouts = new RocketfuelPayouts({
-  clientId: 'YOUR_ID',
-  clientSecret: 'YOUR_SECRET',
-  merchantId: 'YOUR_MERCHANT_ID',
-  environment: 'sandbox', // 'production' | 'qa' | 'preprod' | 'sandbox'
-});
-```
-
-The `RocketfuelPayouts` client exposes three scoped clients:
-
-- **Fiat payouts**: `payouts.fiat`
-- **Crypto payouts**: `payouts.crypto`
-- **Admin operations**: `payouts.admin`
-
-### Fiat payouts (bank payouts)
-
-```ts
-// Get bank configuration for a payee
-const bankConfig = await payouts.fiat.getBankConfiguration({
-  payeeId: 'payee-id',
-  country: 'US',
-  currency: 'USD',
-});
-
-// Save/update bank details
-await payouts.fiat.saveBankDetails('payee-id', {
-  currency: 'USD',
-  country: 'US',
-  // ...bank fields as required by bankConfig
-});
-
-// Get transfer fee quote
-const feeQuote = await payouts.fiat.getTransferFee(
-  { payeeId: 'payee-id', country: 'US', currency: 'USD' },
-  {
-    amount: '100.00',
-    currency: 'USD',
-    country: 'US',
-  },
-);
-
-// Send a fiat transfer
-const transferResult = await payouts.fiat.transfer(
-  { payeeId: 'payee-id', country: 'US', currency: 'USD' },
-  {
-    amount: '100.00',
-    currency: 'USD',
-    country: 'US',
-    // ...bank detail reference / additional payload
-  },
-);
-
-// Check transfer status (fiat or generic payout)
-const status = await payouts.fiat.getTransferStatus('order-id', 'payee-id');
-```
-
-### Crypto payouts
-
-```ts
-// Get payout currencies available for a payee
-const currencies = await payouts.crypto.getCurrencies('payee-id');
-
-// Optionally check address risk/compliance
-await payouts.crypto.checkAddress({
-  address: '0x...',
-  chain: 'ETH',
-  // ...other KYT fields
-});
-
-// Get crypto transfer fee quote
-const cryptoFee = await payouts.crypto.getTransferFee('payee-id', {
-  amount: '10',
-  currency: 'ETH',
-  chain: 'ETH',
-});
-
-// Prepare/validate transfer
-const check = await payouts.crypto.checkTransfer('payee-id', {
-  amount: '10',
-  currency: 'ETH',
-  chain: 'ETH',
-  toAddress: '0x...',
-});
-
-// Execute crypto transfer
-const tx = await payouts.crypto.transfer('payee-id', {
-  amount: '10',
-  currency: 'ETH',
-  chain: 'ETH',
-  toAddress: '0x...',
-});
-
-// Check transfer status (crypto or generic payout)
-const cryptoStatus = await payouts.crypto.getTransferStatus('order-id', 'payee-id');
-```
-
-### Payout admin operations
-
-```ts
-// Invite a new payee
-const newPayee = await payouts.admin.invitePayee({
-  email: 'user@example.com',
-  // ...other payee fields
-});
-
-// Submit KYC for a payee
-await payouts.admin.submitPayeeKyc({
-  payeeId: newPayee.id,
-  // ...KYC payload
-});
-
-// Get a payee's internal balance
-const payeeBalance = await payouts.admin.getPayeeBalance('payee-id');
-
-// Get overall payout admin balance and running balance
-const adminBalance = await payouts.admin.getBalance();
-const runningBalance = await payouts.admin.getRunningBalance();
-
-// Create an allocation transfer
-const allocation = await payouts.admin.createTransferAllocation({
-  payeeId: 'payee-id',
-  amount: '100.00',
-  currency: 'USD',
-  // ...other allocation fields
-});
-
-// Confirm / allocate a transfer
-await payouts.admin.allocateTransfer(allocation.id, {
-  action: 'CONFIRM', // or other allocation actions supported by backend
-});
-```
-
-### Payout webhook verification & events
-
-Use the payout webhook helper to validate webhook signatures and use typed event names:
-
-```ts
-import {
-  PayoutWebhookVerifier,
-  PAYOUT_WEBHOOK_EVENT_TYPE,
-  PAYOUT_WEBHOOK_EVENTS,
-} from '@rkfl/transact-server';
-
-function handlePayoutWebhook(req, res) {
-  const isValid = PayoutWebhookVerifier.verify(req.body);
-
-  if (!isValid) {
-    console.warn('Payout webhook signature verification failed');
-    return res.status(403).send('Invalid signature');
-  }
-
-  // Top-level event metadata
-  const { event, notificationType, timestamp } = req.body;
-
-  // Canonical payload string signed by Rocketfuel
-  const payload = JSON.parse(req.body.data);
-
-  if (event === PAYOUT_WEBHOOK_EVENTS.PayoutStatusChange) {
-    // handle payout status change
-  }
-
-  return res.status(200).send('OK');
-}
-```
-
-## 📦 NPM Commands Documentation
-### 1. npm:login
-
-Logs you into your npm account from the terminal.
-You’ll be prompted for your npm username, password, and email.
-```
-npm run npm:login
-```
-Use this before your first publish or if you’re logged out.
-
-### 2. npm:publish
-Publishes the current package to npm with public access.
-The package name and version must be unique on npm.
-```
-npm run npm:publish
-```
-
-### 3. npm:patch
-Increments the patch version (last digit) in package.json by +1.
-Used for bug fixes or small improvements.
-```
-npm run npm:patch
-```
-Example Version Change:
-```
-1.0.9   → 1.0.10
-1.0.10  → 1.0.11
-```
-### 4. npm:minor
-Increments the minor version (middle digit) by +1 and resets patch to 0.
-Used for adding new features without breaking compatibility.
-```
-npm run npm:minor
-```
-Example Version Change:
-```
-1.0.5   → 1.1.0
-1.2.7   → 1.3.0
-```
-### 5. npm:major
-Increments the major version (first digit) by +1 and resets minor and patch to 0.
-Used for breaking changes or major redesigns.
-```
-npm run npm:major
-```
-Example Version Change:
-```
-1.4.8   → 2.0.0
-2.1.3   → 3.0.0
-```
-## 🚀 Recommended Workflow
-### Login once:
-```
-npm run npm:login
-```
-Make changes to your code.
-
-### Bump version:
-```
-npm run npm:patch
-```
-Minor:
-
-```
-npm run npm:minor
-```
-Major:
-```
-npm run npm:major
-```
-
-### Publish:
-```
-npm run npm:publish
-```
-## 📄 License
+# Rocketfuel SDK (Node.js)
+
+A secure and minimal Node.js SDK to interact with Rocketfuel payment APIs. (This SDK is for Node.js server-side usage.)
+
+## Installation
+
+```bash
+npm i @rkfl/transact-server
+```
+## Documentation
+Click here for more detailed [Documentation](https://docs.rocketfuel.inc/plug-ins-and-sdks/javascript-js/rocketfuel-sdk-nodejs)
+## Usage
+
+### Create order
+
+```ts
+import { Rocketfuel } from '@rocketfuel/plugin';
+
+const client = new Rocketfuel({
+  clientId: 'YOUR_ID',
+  clientSecret: 'YOUR_SECRET',
+  merchantId: 'YOUR_MERCHANT_ID',
+  domain: 'production' // or 'sandbox'
+});
+
+const orderData = {
+  amount: "10",
+  currency: "USD",
+  cart: [
+    {
+      id: "iphone_14_pro_max",
+      name: "iPhone 14 Pro Max",
+      price: "10",
+      quantity: 1
+    }
+  ],
+  customerInfo: {
+    name: "John Doe",
+    email: "john.doe@example.com"
+  },
+  customParameter: {
+    returnMethod: "GET",
+    params: [
+      {
+        name: "submerchant",
+        value: "mobilesale"
+      }
+    ]
+  },
+  merchant_id: '14ec584d-53af-476d-aacd-2b7f025cf21b'
+};
+
+const result = await client.createOrder(orderData);
+
+```
+
+### Transaction Lookup
+To check or confirm the transaction status using order id or Rocketfuel provided transaction id
+
+```
+
+async function checkTransaction(txId) {
+  try {
+    const result = await client.transactionLookup(txId, 'ORDERID');
+    console.log('Transaction Details:', result);
+    // Process the transaction details as needed
+  } catch (error) {
+    console.error('Error fetching transaction details:', error.message);
+  }
+}
+​
+// Example call:
+checkTransaction('12345ABC');
+```
+
+### Webook Verification
+Use this function to verify that a webhook is valid and trusted before processing its contents. It prevents spoofed requests, data tampering, and unauthorized events.
+This function returns true if the signature is valid, otherwise false.
+
+```ts
+function handleWebhook(req, res) {
+  const isValid = client.verifyWebhookSignature(req.body);
+
+  if (!isValid) {
+    console.warn('Webhook signature verification failed');
+    return res.status(403).send('Invalid signature');
+  }
+
+  const payload = JSON.parse(req.body.data.data);
+  console.log('Verified Webhook Payload:', payload);
+
+  // Process your payload
+  res.status(200).send('Webhook received');
+}
+```
+
+## Payouts SDK (Fiat, Crypto & Admin)
+
+The payouts SDK lets you invite payees, manage KYC, allocate/administer balances, and send fiat or crypto payouts using a single high-level client.
+
+### Payout client setup
+
+```ts
+import { RocketfuelPayouts } from '@rkfl/transact-server';
+
+const payouts = new RocketfuelPayouts({
+  clientId: 'YOUR_ID',
+  clientSecret: 'YOUR_SECRET',
+  merchantId: 'YOUR_MERCHANT_ID',
+  environment: 'sandbox', // 'production' | 'qa' | 'preprod' | 'sandbox'
+});
+```
+
+The `RocketfuelPayouts` client exposes three scoped clients:
+
+- **Fiat payouts**: `payouts.fiat`
+- **Crypto payouts**: `payouts.crypto`
+- **Admin operations**: `payouts.admin`
+
+### Fiat payouts (bank payouts)
+
+```ts
+// Get bank configuration for a payee
+const bankConfig = await payouts.fiat.getBankConfiguration({
+  payeeId: 'payee-id',
+  country: 'US',
+  currency: 'USD',
+});
+
+// Save/update bank details
+await payouts.fiat.saveBankDetails('payee-id', {
+  currency: 'USD',
+  country: 'US',
+  // ...bank fields as required by bankConfig
+});
+
+// Get transfer fee quote
+const feeQuote = await payouts.fiat.getTransferFee(
+  { payeeId: 'payee-id', country: 'US', currency: 'USD' },
+  {
+    amount: '100.00',
+    currency: 'USD',
+    country: 'US',
+  },
+);
+
+// Send a fiat transfer
+const transferResult = await payouts.fiat.transfer(
+  { payeeId: 'payee-id', country: 'US', currency: 'USD' },
+  {
+    amount: '100.00',
+    currency: 'USD',
+    country: 'US',
+    // ...bank detail reference / additional payload
+  },
+);
+
+// Check transfer status (fiat or generic payout)
+const status = await payouts.fiat.getTransferStatus('order-id', 'payee-id');
+```
+
+### Crypto payouts
+
+```ts
+// Get payout currencies available for a payee
+const currencies = await payouts.crypto.getCurrencies('payee-id');
+
+// Optionally check address risk/compliance
+await payouts.crypto.checkAddress({
+  address: '0x...',
+  chain: 'ETH',
+  // ...other KYT fields
+});
+
+// Get crypto transfer fee quote
+const cryptoFee = await payouts.crypto.getTransferFee('payee-id', {
+  amount: '10',
+  currency: 'ETH',
+  chain: 'ETH',
+});
+
+// Prepare/validate transfer
+const check = await payouts.crypto.checkTransfer('payee-id', {
+  amount: '10',
+  currency: 'ETH',
+  chain: 'ETH',
+  toAddress: '0x...',
+});
+
+// Execute crypto transfer
+const tx = await payouts.crypto.transfer('payee-id', {
+  amount: '10',
+  currency: 'ETH',
+  chain: 'ETH',
+  toAddress: '0x...',
+});
+
+// Check transfer status (crypto or generic payout)
+const cryptoStatus = await payouts.crypto.getTransferStatus('order-id', 'payee-id');
+```
+
+### Payout admin operations
+
+```ts
+// Invite a new payee
+const newPayee = await payouts.admin.invitePayee({
+  email: 'user@example.com',
+  // ...other payee fields
+});
+
+// Submit KYC for a payee
+await payouts.admin.submitPayeeKyc({
+  payeeId: newPayee.id,
+  // ...KYC payload
+});
+
+// Get a payee's internal balance
+const payeeBalance = await payouts.admin.getPayeeBalance('payee-id');
+
+// Get overall payout admin balance and running balance
+const adminBalance = await payouts.admin.getBalance();
+const runningBalance = await payouts.admin.getRunningBalance();
+
+// Create an allocation transfer
+const allocation = await payouts.admin.createTransferAllocation({
+  payeeId: 'payee-id',
+  amount: '100.00',
+  currency: 'USD',
+  // ...other allocation fields
+});
+
+// Confirm / allocate a transfer
+await payouts.admin.allocateTransfer(allocation.id, {
+  action: 'CONFIRM', // or other allocation actions supported by backend
+});
+```
+
+### Payout webhook verification & events
+
+Use the payout webhook helper to validate webhook signatures and use typed event names:
+
+```ts
+import {
+  PayoutWebhookVerifier,
+  PAYOUT_WEBHOOK_EVENT_TYPE,
+  PAYOUT_WEBHOOK_EVENTS,
+} from '@rkfl/transact-server';
+
+function handlePayoutWebhook(req, res) {
+  const isValid = PayoutWebhookVerifier.verify(req.body);
+
+  if (!isValid) {
+    console.warn('Payout webhook signature verification failed');
+    return res.status(403).send('Invalid signature');
+  }
+
+  // Top-level event metadata
+  const { event, notificationType, timestamp } = req.body;
+
+  // Canonical payload string signed by Rocketfuel
+  const payload = JSON.parse(req.body.data);
+
+  if (event === PAYOUT_WEBHOOK_EVENTS.PayoutStatusChange) {
+    // handle payout status change
+  }
+
+  return res.status(200).send('OK');
+}
+```
+
+## 📦 NPM Commands Documentation
+### 1. npm:login
+
+Logs you into your npm account from the terminal.
+You’ll be prompted for your npm username, password, and email.
+```
+npm run npm:login
+```
+Use this before your first publish or if you’re logged out.
+
+### 2. npm:publish
+Publishes the current package to npm with public access.
+The package name and version must be unique on npm.
+```
+npm run npm:publish
+```
+
+### 3. npm:patch
+Increments the patch version (last digit) in package.json by +1.
+Used for bug fixes or small improvements.
+```
+npm run npm:patch
+```
+Example Version Change:
+```
+1.0.9   → 1.0.10
+1.0.10  → 1.0.11
+```
+### 4. npm:minor
+Increments the minor version (middle digit) by +1 and resets patch to 0.
+Used for adding new features without breaking compatibility.
+```
+npm run npm:minor
+```
+Example Version Change:
+```
+1.0.5   → 1.1.0
+1.2.7   → 1.3.0
+```
+### 5. npm:major
+Increments the major version (first digit) by +1 and resets minor and patch to 0.
+Used for breaking changes or major redesigns.
+```
+npm run npm:major
+```
+Example Version Change:
+```
+1.4.8   → 2.0.0
+2.1.3   → 3.0.0
+```
+## 🚀 Recommended Workflow
+### Login once:
+```
+npm run npm:login
+```
+Make changes to your code.
+
+### Bump version:
+```
+npm run npm:patch
+```
+Minor:
+
+```
+npm run npm:minor
+```
+Major:
+```
+npm run npm:major
+```
+
+### Publish:
+```
+npm run npm:publish
+```
+## 📄 License
 MIT License © RocketFuel Blockchain, Inc.

package/package.json

@@ -2,7 +2,7 @@
   "name": "@rkfl/transact-server",
   "main": "./dist/index.js",
   "type": "module",
-  "version": "2.1.1-alpha.0",
+  "version": "2.2.0-alpha.0",
   "scripts": {
     "build": "rollup -c",
     "npm:login": "npm login",

package/dist/constants.d.ts

@@ -1,73 +0,0 @@
-export declare const apiDomains: {
-    readonly production: "https://app.rocketfuel.inc/api";
-    readonly qa: "https://qa-app.rfdemo.co/api";
-    readonly preprod: "https://preprod-app.rocketdemo.net/api";
-    readonly sandbox: "https://app-sandbox.rocketfuel.inc/api";
-};
-export type Environment = keyof typeof apiDomains;
-export interface HttpError extends Error {
-    status: number;
-}
-export interface CartItem {
-    id: string | null;
-    price: number;
-    name: string;
-    quantity: number;
-    key?: number;
-    totalPrice?: number;
-    isSubscription?: boolean | null;
-    frequency?: "weekly" | "monthly" | "quarterly" | "half-yearly" | "yearly" | "" | null;
-    subscriptionPeriod?: string | null;
-    merchantSubscriptionId?: string | null;
-    autoRenewal?: boolean | null;
-    isSubscriptionRenewal?: boolean | null;
-    subscriptionId?: string | null;
-    refundable?: boolean;
-}
-export interface CustomerInfo {
-    name: string;
-    email?: string;
-    phone?: string;
-    address?: string;
-    allowLoginWithoutEmail?: boolean;
-    userIdentifier?: string;
-}
-export interface ShippingAddress {
-    firstname?: string;
-    lastname?: string;
-    phoneNo?: string;
-    address1: string;
-    address2?: string;
-    state: string;
-    city: string;
-    zipcode?: string;
-    country: string;
-    landmark?: string | null;
-    email?: string | null;
-}
-export interface CustomParameter {
-    returnMethod: any;
-    params: any;
-}
-export interface FeeConfiguration {
-    type: "FIAT" | "PERCENT";
-    value: number;
-}
-export interface SiteInfo {
-    siteUrl?: string | null;
-    siteName?: string | null;
-    siteLogo?: string | null;
-}
-export interface CartData {
-    merchant_id: string;
-    amount: string;
-    cart: CartItem[];
-    currency: string;
-    order?: string;
-    redirectUrl?: string;
-    customerInfo?: CustomerInfo;
-    shippingAddress?: ShippingAddress | null;
-    customParameter?: CustomParameter | null;
-    feeConfiguration?: FeeConfiguration | null;
-    siteInfo?: SiteInfo | null;
-}