@100pay-hq/100pay.js 1.4.12 → 1.4.13

package/README.MD

@@ -61,28 +61,28 @@ yarn add @100pay-hq/100pay.js
 ## Quick Start
 
 ```typescript
-import { Pay100 } from '@100pay-hq/100pay.js';
+import { Pay100 } from "@100pay-hq/100pay.js";
 
 // Initialize the 100Pay client
 const client = new Pay100({
-  publicKey: 'your_public_key',
-  secretKey: 'your_secret_key' // Required for server-side operations
+  publicKey: "your_public_key",
+  secretKey: "your_secret_key", // Required for server-side operations
 });
 
 // Verify a transaction
 async function verifyTransaction(transactionId) {
   try {
     const result = await client.verify(transactionId);
-    
-    if (result.status === 'success') {
-      console.log('Transaction verified:', result.data);
+
+    if (result.status === "success") {
+      console.log("Transaction verified:", result.data);
       return result.data;
     } else {
-      console.error('Verification failed:', result.message);
+      console.error("Verification failed:", result.message);
       return null;
     }
   } catch (error) {
-    console.error('Error:', error.message);
+    console.error("Error:", error.message);
     throw error;
   }
 }
@@ -94,9 +94,9 @@ async function verifyTransaction(transactionId) {
 
 ```typescript
 const client = new Pay100({
-  publicKey: string,  // Your 100Pay public API key (required)
-  secretKey?: string, // Your 100Pay secret API key (required for server-side operations)
-  baseUrl?: string    // Optional custom API base URL (defaults to https://api.100pay.co)
+  publicKey: string, // Your 100Pay public API key (required)
+  secretKey: string, // Your 100Pay secret API key (required for server-side operations)
+  baseUrl: string, // Optional custom API base URL (defaults to https://api.100pay.co)
 });
 ```
 
@@ -109,8 +109,8 @@ const result = await client.verify(transactionId);
 
 **Parameters:**
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
+| Parameter     | Type   | Description                                |
+| ------------- | ------ | ------------------------------------------ |
 | transactionId | string | The unique ID of the transaction to verify |
 
 **Returns:**
@@ -118,7 +118,7 @@ const result = await client.verify(transactionId);
 ```typescript
 interface IVerifyResponse {
   status: "success" | "error";
-  data: ITransactionData | Record<string, never>;
+  data?: ITransactionData | null;
   message?: string;
 }
 ```
@@ -128,8 +128,8 @@ interface IVerifyResponse {
 ```typescript
 try {
   const result = await client.verify("tx_123456789");
-  
-  if (result.status === 'success') {
+
+  if (result.status === "success") {
     // Payment is valid
     const { amount, currency, status } = result.data;
     // Process order fulfillment
@@ -159,12 +159,12 @@ const subaccount = await client.subaccounts.create({
   owner: {
     name: "Partner Store",
     email: "partner@example.com",
-    phone: "+1234567890"
+    phone: "+1234567890",
   },
   metadata: {
     storeId: "store-123",
-    region: "US"
-  }
+    region: "US",
+  },
 });
 ```
 
@@ -172,12 +172,12 @@ const subaccount = await client.subaccounts.create({
 
 ```typescript
 interface CreateSubAccountData {
-  symbols: string[];            // List of supported cryptocurrencies
-  networks: string[];           // List of supported blockchain networks
+  symbols: string[]; // List of supported cryptocurrencies
+  networks: string[]; // List of supported blockchain networks
   owner: {
-    name: string;               // Owner's name
-    email: string;              // Owner's email
-    phone: string;              // Owner's phone number
+    name: string; // Owner's name
+    email: string; // Owner's email
+    phone: string; // Owner's phone number
   };
   metadata: Record<string, unknown>; // Custom metadata for the subaccount
 }
@@ -196,13 +196,13 @@ interface Account {
     available: number | null;
     locked: number | null;
   };
-  accountType: string;         // e.g. "subaccount"
-  walletType: string;          // e.g. "crypto"
-  status: string;              // e.g. "active"
+  accountType: string; // e.g. "subaccount"
+  walletType: string; // e.g. "crypto"
+  status: string; // e.g. "active"
   _id: string;
-  name: string;                // e.g. "Tether USDT"
-  symbol: string;              // e.g. "USDT"
-  decimals: string;            // e.g. "18"
+  name: string; // e.g. "Tether USDT"
+  symbol: string; // e.g. "USDT"
+  decimals: string; // e.g. "18"
   account: AccountDetails;
   contractAddress: string;
   logo: string;
@@ -250,21 +250,21 @@ interface Crypto {
 ```typescript
 try {
   const result = await client.subaccounts.create({
-    symbols: ["USDT", "BTC"], 
+    symbols: ["USDT", "BTC"],
     networks: ["ETHEREUM"],
     owner: {
       name: "Merchant Store",
       email: "merchant@example.com",
-      phone: "+1234567890"
+      phone: "+1234567890",
     },
     metadata: {
-      businessType: "ecommerce"
-    }
+      businessType: "ecommerce",
+    },
   });
-  
+
   console.log(`Created ${result.accounts.length} accounts for the subaccount`);
   // Store wallet addresses for each account
-  result.accounts.forEach(account => {
+  result.accounts.forEach((account) => {
     console.log(`${account.symbol} wallet: ${account.account.address}`);
   });
 } catch (error) {
@@ -282,7 +282,7 @@ const conversion = await client.conversion.preview({
   amount: 100,
   from_symbol: "BTC",
   to_symbol: "USDT",
-  appId: "your_app_id" // Optional
+  appId: "your_app_id", // Optional
 });
 ```
 
@@ -290,14 +290,18 @@ const conversion = await client.conversion.preview({
 
 ```typescript
 interface CurrencyConversionPayload {
-  amount: number;      // Amount to convert
-  from_symbol: string; // Source currency symbol (snake_case)
-  to_symbol: string;   // Target currency symbol (snake_case)
-  appId?: string;      // Optional application ID
-  mode?: string;       // Optional conversion mode
+  amount: number; // Amount to convert
+  from_symbol?: string; // Source currency symbol (snake_case)
+  to_symbol?: string; // Target currency symbol (snake_case)
+  fromSymbol?: string; // Source currency symbol (camelCase) - for backward compatibility
+  toSymbol?: string; // Target currency symbol (camelCase) - for backward compatibility
+  appId?: string; // Optional application ID
+  mode?: string; // Optional conversion mode
 }
 ```
 
+> **Note:** You can use either `from_symbol`/`to_symbol` (snake_case) or `fromSymbol`/`toSymbol` (camelCase). The SDK supports both formats for backward compatibility.
+
 **Returns:**
 
 The preview may return a simple result or an enhanced response with more details:
@@ -331,13 +335,17 @@ try {
   const preview = await client.conversion.preview({
     amount: 0.5,
     from_symbol: "BTC",
-    to_symbol: "USDT"
+    to_symbol: "USDT",
   });
-  
+
   if ("convertedAmount" in preview) {
     console.log(`You will receive: ${preview.convertedAmount} USDT`);
-    console.log(`Exchange rate: 1 BTC = ${preview.toRate / preview.fromRate} USDT`);
-    console.log(`Total fees: ${preview.feeInUSD} USD (${preview.feeInFromCurrency} BTC)`);
+    console.log(
+      `Exchange rate: 1 BTC = ${preview.toRate / preview.fromRate} USDT`
+    );
+    console.log(
+      `Total fees: ${preview.feeInUSD} USD (${preview.feeInFromCurrency} BTC)`
+    );
   } else {
     // Handle enhanced response
     console.log("Enhanced conversion preview:", preview);
@@ -355,21 +363,24 @@ Transfer assets between wallets and manage transfer operations:
 // Execute an asset transfer
 const transfer = await client.transfer.executeTransfer({
   amount: 100,
-  currency: "USDT",
-  recipientAddress: "0x1234567890abcdef...",
-  // ... other transfer parameters
+  symbol: "USDT", // Use 'symbol' not 'currency'
+  to: "0x1234567890abcdef...", // Use 'to' not 'recipientAddress'
+  transferType: "external", // Optional: "internal" or "external"
+  note: "Payment for services", // Optional note
 });
 
 // Get transfer history
 const history = await client.transfer.getHistory({
   page: 1,
-  limit: 10
+  limit: 10,
+  symbols: ["USDT"], // Optional filter by symbols
+  type: "debit", // Optional filter by type
 });
 
 // Calculate transfer fees
 const fees = await client.transfer.calculateFee({
-  currency: "USDT",
-  transferType: "crypto"
+  symbol: "USDT", // Use 'symbol' not 'currency'
+  transferType: "external", // Use "internal" or "external"
 });
 ```
 
@@ -395,12 +406,12 @@ console.log(`${bankList.data.count} banks available`);
 // Verify a bank account
 const verification = await client.bankTransfer.verifyBank({
   bankCode: "044",
-  accountNumber: "1234567890"
+  accountNumber: "1234567890",
 });
 
 if (verification.data.verified) {
   console.log(`Account verified: ${verification.data.accountName}`);
-  
+
   // Execute bank transfer
   const transfer = await client.bankTransfer.transfer({
     beneficiaryBankCode: "044",
@@ -409,9 +420,9 @@ if (verification.data.verified) {
     amount: 500, // Amount in Naira (NGN 500)
     narration: "Payment for services",
     paymentReference: `ref_${Date.now()}`,
-    saveBeneficiary: true
+    saveBeneficiary: true,
   });
-  
+
   console.log(`Transfer initiated: ${transfer.data.transfer.sessionId}`);
 }
 ```
@@ -452,7 +463,7 @@ interface IBank {
 ```typescript
 const verification = await client.bankTransfer.verifyBank({
   bankCode: "044",
-  accountNumber: "1234567890"
+  accountNumber: "1234567890",
 });
 ```
 
@@ -460,7 +471,7 @@ const verification = await client.bankTransfer.verifyBank({
 
 ```typescript
 interface IVerifyBankData {
-  bankCode: string;      // Bank code from the bank list
+  bankCode: string; // Bank code from the bank list
   accountNumber: string; // Account number to verify
 }
 ```
@@ -491,7 +502,7 @@ const transfer = await client.bankTransfer.transfer({
   amount: 50000,
   narration: "Payment description",
   paymentReference: "unique_ref_123",
-  saveBeneficiary: true
+  saveBeneficiary: true,
 });
 ```
 
@@ -500,45 +511,52 @@ const transfer = await client.bankTransfer.transfer({
 #### Get Authorization URL
 
 ```typescript
-const authUrl = client.oauth.getAuthorizationUrl({
-  redirectUri: "https://yourapp.com/callback",
+const authUrl = await client.oauth.getAuthorizationUrl({
+  client_id: "your_client_id",
+  redirect_uri: "https://yourapp.com/callback",
   scope: "read_user_info read_app_info",
-  state: "some_random_state"
+  state: "some_random_state",
 });
 ```
 
-#### Get Access Token
+#### Exchange Code for Access Token
 
 ```typescript
-const tokenData = await client.oauth.getAccessToken({
+const tokenResponse = await client.oauth.exchangeCodeForToken({
+  grant_type: "authorization_code",
   code: "authorization_code",
-  redirectUri: "https://yourapp.com/callback"
+  client_id: "your_client_id",
+  client_secret: "your_client_secret",
+  redirect_uri: "https://yourapp.com/callback",
 });
+const tokenData = tokenResponse.data;
 ```
 
 #### Get User Info
 
 ```typescript
-const userInfo = await client.oauth.getUserInfo(tokenData.access_token);
+const userInfoResponse = await client.oauth.getUserInfo(tokenData.access_token);
+const userInfo = userInfoResponse.data;
 ```
 
 #### Get App Info
 
 ```typescript
-const appInfo = await client.oauth.getAppInfo(tokenData.access_token);
+const appInfoResponse = await client.oauth.getAppInfo(tokenData.access_token);
+const appInfo = appInfoResponse.data;
 ```
 
 **Parameters:**
 
 ```typescript
 interface IBankTransferData {
-  beneficiaryBankCode: string;      // Recipient's bank code
+  beneficiaryBankCode: string; // Recipient's bank code
   beneficiaryAccountNumber: string; // Recipient's account number
-  beneficiaryAccountName: string;   // Recipient's account name
-  amount: number;                   // Amount in Naira
-  narration: string;                // Transfer description
-  paymentReference: string;         // Unique payment reference
-  saveBeneficiary: boolean;         // Whether to save this beneficiary
+  beneficiaryAccountName: string; // Recipient's account name
+  amount: number; // Amount in Naira
+  narration: string; // Transfer description
+  paymentReference: string; // Unique payment reference
+  saveBeneficiary: boolean; // Whether to save this beneficiary
 }
 ```
 
@@ -569,23 +587,33 @@ The SDK provides methods for OAuth 2.0 authorization:
 
 ```typescript
 // Get authorization URL
-const authUrl = client.oauth.getAuthorizationUrl({
-  redirectUri: "https://yourapp.com/callback",
+const authUrl = await client.oauth.getAuthorizationUrl({
+  client_id: "your_client_id",
+  redirect_uri: "https://yourapp.com/callback",
   scope: "read_user_info read_app_info",
-  state: "some_random_state"
+  state: "some_random_state",
 });
 
-// Get access token
-const tokenData = await client.oauth.getAccessToken({
+// Exchange code for access token
+const tokenResponse = await client.oauth.exchangeCodeForToken({
+  grant_type: "authorization_code",
   code: "authorization_code",
-  redirectUri: "https://yourapp.com/callback"
+  client_id: "your_client_id",
+  client_secret: "your_client_secret",
+  redirect_uri: "https://yourapp.com/callback",
 });
 
 // Get user info
-const userInfo = await client.oauth.getUserInfo(tokenData.access_token);
+const userInfoResponse = await client.oauth.getUserInfo(
+  tokenResponse.data.access_token
+);
+const userInfo = userInfoResponse.data;
 
 // Get app info
-const appInfo = await client.oauth.getAppInfo(tokenData.access_token);
+const appInfoResponse = await client.oauth.getAppInfo(
+  tokenResponse.data.access_token
+);
+const appInfo = appInfoResponse.data;
 ```
 
 ### Generic API Requests
@@ -594,9 +622,9 @@ The SDK provides a generic `request` method for making any API call to the 100Pa
 
 ```typescript
 const response = await client.request<ResponseType>(
-  method,   // 'GET', 'POST', 'PUT', or 'DELETE'
+  method, // 'GET', 'POST', 'PUT', or 'DELETE'
   endpoint, // API endpoint path
-  data      // Request payload
+  data // Request payload
 );
 ```
 
@@ -605,8 +633,8 @@ const response = await client.request<ResponseType>(
 ```typescript
 // Get user app balance
 const balance = await client.request<BalanceResponse>(
-  'GET',
-  '/api/v1/user-apps/:appId/wallet-balance/:symbol'
+  "GET",
+  "/api/v1/user-apps/:appId/wallet-balance/:symbol"
 );
 ```
 
@@ -644,14 +672,25 @@ Client-side operations can use public key only, while server-side operations req
 This package is built with TypeScript and includes full type definitions. The main types are exported for your convenience:
 
 ```typescript
-import { 
-  Pay100, 
-  PaymentVerificationError, 
+import {
+  Pay100,
+  PaymentVerificationError,
+  ITransactionData,
+  IVerifyResponse,
   CreateSubAccountData,
+  CreateSubAccountResponse,
   CurrencyConversionPayload,
   CurrencyConversionResult,
+  EnhancedConversionResponse,
   Account,
   AccountDetails,
+  ITransferAssetData,
+  ITransferAssetResponse,
+  ITransferHistoryParams,
+  ITransferHistoryResponse,
+  ITransferFeeParams,
+  ITransferFeeResponse,
+  ISupportedWalletResponse,
   IBankListResponse,
   IBankTransferData,
   IBankTransferResponse,
@@ -660,8 +699,8 @@ import {
   IOAuthApp,
   ITokenData,
   IUserInfo,
-  IAppInfo
-} from '@100pay-hq/100pay.js';
+  IAppInfo,
+} from "@100pay-hq/100pay.js";
 ```
 
 ## Common Use Cases
@@ -681,16 +720,16 @@ const subaccount = await client.subaccounts.create({
   owner: {
     name: "Partner Name",
     email: "partner@example.com",
-    phone: "+1234567890"
+    phone: "+1234567890",
   },
   metadata: {
-    partnerId: "partner-123"
-  }
+    partnerId: "partner-123",
+  },
 });
 
 // Save the subaccount information for future use
 console.log(`Created subaccount with ${subaccount.accounts.length} wallets`);
-subaccount.accounts.forEach(account => {
+subaccount.accounts.forEach((account) => {
   console.log(`${account.symbol} wallet: ${account.account.address}`);
 });
 ```
@@ -702,14 +741,18 @@ subaccount.accounts.forEach(account => {
 const preview = await client.conversion.preview({
   amount: 1000,
   from_symbol: "USDT",
-  to_symbol: "BTC"
+  to_symbol: "BTC",
 });
 
 // Show user the conversion details
 if ("convertedAmount" in preview) {
   console.log(`You will receive approximately ${preview.convertedAmount} BTC`);
-  console.log(`Exchange rate: 1 USDT = ${preview.toRate / preview.fromRate} BTC`);
-  console.log(`Fee: ${preview.feeInFromCurrency} USDT (${preview.feeInUSD} USD)`);
+  console.log(
+    `Exchange rate: 1 USDT = ${preview.toRate / preview.fromRate} BTC`
+  );
+  console.log(
+    `Fee: ${preview.feeInFromCurrency} USDT (${preview.feeInUSD} USD)`
+  );
 } else {
   // Handle enhanced response
   console.log("Enhanced conversion preview:", preview);
@@ -725,23 +768,25 @@ async function performBankTransfer() {
     // 1. Get available banks
     const banks = await client.bankTransfer.getBankList();
     console.log(`Available banks: ${banks.data.count}`);
-    
+
     // 2. Find the desired bank
-    const targetBank = banks.data.banks.find(bank => bank.name?.includes("Access"));
+    const targetBank = banks.data.banks.find((bank) =>
+      bank.name?.includes("Access")
+    );
     if (!targetBank) throw new Error("Bank not found");
-    
+
     // 3. Verify the recipient's account
     const verification = await client.bankTransfer.verifyBank({
       bankCode: targetBank.bankCode!,
-      accountNumber: "1234567890"
+      accountNumber: "1234567890",
     });
-    
+
     if (!verification.data.verified) {
       throw new Error("Account verification failed");
     }
-    
+
     console.log(`Account verified: ${verification.data.accountName}`);
-    
+
     // 4. Execute the transfer
     const transfer = await client.bankTransfer.transfer({
       beneficiaryBankCode: targetBank.bankCode!,
@@ -750,12 +795,11 @@ async function performBankTransfer() {
       amount: 500, // NGN 500 in Naira
       narration: "Payment for services rendered",
       paymentReference: `PAY_${Date.now()}`,
-      saveBeneficiary: true
+      saveBeneficiary: true,
     });
-    
+
     console.log(`Transfer successful: ${transfer.data.transfer.sessionId}`);
     return transfer.data.transfer;
-    
   } catch (error) {
     console.error(`Bank transfer failed: ${error.message}`);
     throw error;
@@ -770,27 +814,34 @@ async function performBankTransfer() {
 async function performOAuth() {
   try {
     // 1. Get authorization URL
-    const authUrl = client.oauth.getAuthorizationUrl({
-      redirectUri: "https://yourapp.com/callback",
+    const authUrl = await client.oauth.getAuthorizationUrl({
+      client_id: "your_client_id",
+      redirect_uri: "https://yourapp.com/callback",
       scope: "read_user_info read_app_info",
-      state: "some_random_state"
+      state: "some_random_state",
     });
     console.log(`Authorization URL: ${authUrl}`);
-    
-    // 2. Get access token
-    const tokenData = await client.oauth.getAccessToken({
+
+    // 2. Exchange code for access token
+    const tokenResponse = await client.oauth.exchangeCodeForToken({
+      grant_type: "authorization_code",
       code: "authorization_code",
-      redirectUri: "https://yourapp.com/callback"
+      client_id: "your_client_id",
+      client_secret: "your_client_secret",
+      redirect_uri: "https://yourapp.com/callback",
     });
-    
+
     // 3. Get user info
-    const userInfo = await client.oauth.getUserInfo(tokenData.access_token);
-    console.log(`User info: ${userInfo}`);
-    
+    const userInfoResponse = await client.oauth.getUserInfo(
+      tokenResponse.data.access_token
+    );
+    console.log(`User info:`, userInfoResponse.data);
+
     // 4. Get app info
-    const appInfo = await client.oauth.getAppInfo(tokenData.access_token);
-    console.log(`App info: ${appInfo}`);
-    
+    const appInfoResponse = await client.oauth.getAppInfo(
+      tokenResponse.data.access_token
+    );
+    console.log(`App info:`, appInfoResponse.data);
   } catch (error) {
     console.error(`OAuth workflow failed: ${error.message}`);
     throw error;
@@ -835,7 +886,7 @@ interface BankTransferWebhook {
 **Webhook Event Types:**
 
 - `bank_transfer.debit` - Outgoing bank transfer initiated
-- `bank_transfer.credit` - Incoming bank transfer received  
+- `bank_transfer.credit` - Incoming bank transfer received
 - `wallet.deposit` - Wallet deposit received
 - `wallet.deposit.internal` - Internal wallet deposit received
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@100pay-hq/100pay.js",
-  "version": "1.4.12",
+  "version": "1.4.13",
   "description": "100Pay.js is the official Nodejs API wrapper SDK that lets you easily verify crypto payments, run bulk payout, transfer assets and many more.",
   "type": "module",
   "main": "./dist/index.cjs",