paj_ramp 1.0.0

package/README.md

@@ -0,0 +1,254 @@
+# paj_ramp
+
+Paj Ramp is a crypto offramp API designed to allow users to convert Solana-based digital assets to fiat and transfer the resulting funds to traditional bank accounts. This backend service acts as a bridge between the Solana blockchain and the traditional banking system, enabling secure, authenticated, and user-friendly offboarding of funds from Web3 to Web2.
+
+> _A simple wrapper for communicating with paj_ramp's backend endpoints — no manual API calls required._
+
+### _“Send SOL. Get Naira.”_
+
+> _The goal is to let users withdraw their crypto holdings from a Solana wallet and receive fiat currency in their linked bank accounts — all through a simple, authenticated API integration._
+
+---
+
+## 🚀 Features
+
+- ✅ Easy-to-use functions for all backend endpoints
+- 🔐 Handles Session Management
+- 🧱 Clean, modular API
+- 🕊️ No need to write `fetch()` or `axios` manually
+- 🕸️ Handles Bank Operations like getting banks, adding banks, resolving banks and getting banks linked to the account
+
+---
+
+## 📦 Installation
+
+```bash
+# With npm
+npm install paj_ramp
+
+# With yarn
+yarn add paj_ramp
+```
+
+---
+
+## 📘 Usage Examples
+
+### Get tx pool address
+
+```bash
+import { getTXPoolAddress } from 'paj_ramp';
+
+const txpooladdress = await getTXPoolAddress();
+
+# Response
+{
+  address: string,
+}
+```
+
+### Get rate
+
+```bash
+import { getRate } from 'paj_ramp';
+
+const rate = await getRate();
+
+# Response
+{
+  baseCurrency: string,
+  targetCurrency: string,
+  rate: number
+}
+```
+
+### Get rate with amount
+
+```bash
+import { getRate } from 'paj_ramp';
+
+const rate = await getRate(50000);
+
+# Response
+{
+  rate: {
+    baseCurrency: string,
+    targetCurrency: string,
+    rate: number
+  },
+  amounts: {
+    userTax: number,
+    merchantTax": number,
+    amountUSD": number,
+    userAmountFiat": number
+   }
+}
+```
+
+### Initiate Session
+
+```bash
+import { initiate } from 'paj_ramp';
+
+const initialized = await initiate('your_email@gmail.com');
+
+# Response
+{
+  email: string
+}
+```
+
+### Verify Session
+
+```bash
+import { verify } from 'paj_ramp';
+
+const verified = await verify('your_email@gmail.com', '1234', 'device signature');
+
+# Response
+{
+  email: string,
+  isActive: string,
+  expiresAt: string,
+  token: string
+}
+```
+
+### Get Banks: Get list of banks
+
+```bash
+import { getBanks } from 'paj_ramp';
+
+const banks = await getBanks();
+
+# Response
+[
+  {
+    id: string,
+    name: string,
+    country: string
+  }
+]
+```
+
+### Resolve Bank Account
+
+```bash
+import { resolveBankAccount } from 'paj_ramp';
+
+const resolvedBankAccount = await resolveBankAccount('bank id', 'account number');
+
+# Response
+{
+  accountName: string,
+  accountNumber: string,
+  bank: {
+  id: string,
+    name: string,
+    code: string,
+    country: string,
+  }
+}
+```
+
+### Add Bank Account
+
+```bash
+import { addBankAccount } from 'paj_ramp';
+
+const addedBankAccount = await addBankAccount('token', 'bank id', 'account number');
+
+# Response
+{
+  id: string,
+  accountName: string,
+  accountNumber: string,
+  bank: string
+}
+```
+
+### Get Bank Accounts
+
+```bash
+import { getBankAccounts } from 'paj_ramp';
+
+const addedBankAccount = await getBankAccounts('token');
+
+# Response
+[
+  {
+    id: string,
+    accountName: string,
+    accountNumber: string,
+    bank: string
+  }
+]
+```
+
+### Get Wallet Info
+
+```bash
+import { getWallet } from 'paj_ramp';
+
+const wallet = await getWallet('wallet public key');
+
+# Response
+{
+  id: string,
+  publicKey: string,
+  bankAccount: {
+    id: string,
+    accountName: string,
+    accountNumber: string,
+    bank: string
+  }
+}
+```
+
+### Add Wallet
+
+```bash
+import { addWallet } from 'paj_ramp';
+
+const addedWallet = await addWallet('token', 'bank account id', 'secret key');
+
+# Response
+{
+  id: string,
+  publicKey: string,
+  bankAccount: {
+    id: string,
+    accountName: string,
+    accountNumber: string,
+    bank: string
+  }
+}
+```
+
+### Switch Bank Account on Wallet
+
+```bash
+import { switchWalletBankAccount } from 'paj_ramp';
+
+const switchedWallet = await switchWalletBankAccount('token','bank account id to switch to', 'wallet id', 'secret key');
+
+# Response
+{
+  id: string,
+  publicKey: string,
+  bankAccount: {
+    id: string,
+    accountName: string,
+    accountNumber: string,
+    bank: string
+  }
+}
+```
+
+---
+
+## 🧑‍💻 Author
+
+Your Name — Gospel Chidiebube Chukwu
+
+

package/__tests__/getTXPoolAddress.test.ts

@@ -0,0 +1,24 @@
+import { getTXPoolAddress } from '../lib/getTXPoolAddress';
+import * as api from '../utils/api';
+
+describe('getTXPoolAddress', () => {
+  const mockAddress = 'FakeSolanaAddress123';
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('should return tx pool address when API call succeeds', async () => {
+    jest.spyOn(api, 'get').mockResolvedValue({ address: mockAddress });
+
+    const result = await getTXPoolAddress();
+    expect(result).toEqual({ address: mockAddress });
+  });
+
+  it('should throw an error when API call fails', async () => {
+    const error = new Error('API Failure');
+    jest.spyOn(api, 'get').mockRejectedValue(error);
+
+    await expect(getTXPoolAddress()).rejects.toThrow('API Failure');
+  });
+});

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { getTXPoolAddress } from './lib/getTXPoolAddress.js';
+export { getRate } from './lib/getRate.js';
+export { initiate } from './lib/initiate.js';
+export { verify } from './lib/verify.js';
+export { getBanks } from './lib/getBanks.js';
+export { resolveBankAccount } from './lib/resolveBankAccount.js';
+export { addBankAccount } from './lib/addBankAccount.js';
+export { getBankAccounts } from './lib/getBankAccounts.js';
+export { getWallet } from './lib/getWallet.js';
+export { addWallet } from './lib/addWallet.js';
+export { switchWalletBankAccount } from './lib/switchWalletBankAccount.js';

package/dist/index.js

@@ -0,0 +1,16 @@
+//Web3.js - A JavaScript library for interacting with the Web3 ecosystem.
+//Wallet Info
+export { getTXPoolAddress } from './lib/getTXPoolAddress.js';
+export { getRate } from './lib/getRate.js';
+//Session Management
+export { initiate } from './lib/initiate.js';
+export { verify } from './lib/verify.js';
+//Banking Operations
+export { getBanks } from './lib/getBanks.js';
+export { resolveBankAccount } from './lib/resolveBankAccount.js';
+export { addBankAccount } from './lib/addBankAccount.js';
+export { getBankAccounts } from './lib/getBankAccounts.js';
+//Wallet Operations
+export { getWallet } from './lib/getWallet.js';
+export { addWallet } from './lib/addWallet.js';
+export { switchWalletBankAccount } from './lib/switchWalletBankAccount.js';

package/dist/lib/addBankAccount.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Adds a new bank account by sending the provided token, bank ID, and account number to the public API.
+ * Returns the added bank account details or throws an error if the request fails.
+ *
+ * Args:
+ *   token: The authentication token for the request.
+ *   bankId: The ID of the bank.
+ *   accountNumber: The bank account number to add.
+ *
+ * Returns:
+ *   An object containing the new bank account's id, accountName, accountNumber, and bank.
+ *
+ * Raises:
+ *   Throws an error if the request fails.
+ */
+export declare const addBankAccount: (token: string, bankId: string, accountNumber: string) => Promise<{
+    id: string;
+    accountName: string;
+    accountNumber: string;
+    bank: string;
+}>;

package/dist/lib/addBankAccount.js

@@ -0,0 +1,30 @@
+import { post } from '../utils/api.js';
+/**
+ * Adds a new bank account by sending the provided token, bank ID, and account number to the public API.
+ * Returns the added bank account details or throws an error if the request fails.
+ *
+ * Args:
+ *   token: The authentication token for the request.
+ *   bankId: The ID of the bank.
+ *   accountNumber: The bank account number to add.
+ *
+ * Returns:
+ *   An object containing the new bank account's id, accountName, accountNumber, and bank.
+ *
+ * Raises:
+ *   Throws an error if the request fails.
+ */
+export const addBankAccount = async (token, bankId, accountNumber) => {
+    try {
+        return await post('/pub/bankAccount', {
+            bankId,
+            accountNumber,
+        }, {
+            Authorization: `Bearer ${token}`,
+        });
+    }
+    catch (err) {
+        console.error('Error adding bank account:', err);
+        throw err;
+    }
+};

package/dist/lib/addWallet.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Adds a new wallet for the user.
+ * Returns the added wallet object or throws an error if the request fails.
+ *
+ * Returns:
+ *   An object containing id, accountName, accountNumber, and bank of the bank account.
+ *
+ * Raises:
+ *   Throws an error if the wallet file is not found or if the secret key is invalid.
+ */
+export declare const addWallet: (apiKey: string, accountId: string, secretKey: Uint8Array) => Promise<void>;

package/dist/lib/addWallet.js

@@ -0,0 +1,27 @@
+import { post } from "../utils/api.js";
+import { getWalletBody } from "../utils/getWalletBody.js";
+/**
+ * Adds a new wallet for the user.
+ * Returns the added wallet object or throws an error if the request fails.
+ *
+ * Returns:
+ *   An object containing id, accountName, accountNumber, and bank of the bank account.
+ *
+ * Raises:
+ *   Throws an error if the wallet file is not found or if the secret key is invalid.
+ */
+export const addWallet = async (apiKey, accountId, secretKey) => {
+    try {
+        const body = await getWalletBody(accountId, secretKey);
+        if (!body) {
+            throw new Error("Failed to get wallet body");
+        }
+        const response = await post("/pub/wallet", body, {
+            Authorization: `Bearer ${apiKey}`,
+        });
+    }
+    catch (err) {
+        console.error("Error adding wallet:", err);
+        throw err;
+    }
+};

package/dist/lib/getBankAccounts.d.ts

@@ -0,0 +1,18 @@
+type GetBankAccountsType = {
+    id: string;
+    accountName: string;
+    accountNumber: string;
+    bank: string;
+};
+/**
+ * Fetches a list of added bank accounts from the public API endpoint.
+ * Returns an array of bank account objects or throws an error if the request fails.
+ *
+ * Returns:
+ *   An array of objects, each containing id, accountName, accountNumber, and bank of a bank account.
+ *
+ * Raises:
+ *   Throws an error if the request fails.
+ */
+export declare const getBankAccounts: (apiKey: string) => Promise<GetBankAccountsType[]>;
+export {};

package/dist/lib/getBankAccounts.js

@@ -0,0 +1,22 @@
+import { get } from "../utils/api.js";
+/**
+ * Fetches a list of added bank accounts from the public API endpoint.
+ * Returns an array of bank account objects or throws an error if the request fails.
+ *
+ * Returns:
+ *   An array of objects, each containing id, accountName, accountNumber, and bank of a bank account.
+ *
+ * Raises:
+ *   Throws an error if the request fails.
+ */
+export const getBankAccounts = async (apiKey) => {
+    try {
+        return await get(`/pub/bankaccount`, {}, {
+            Authorization: `Bearer ${apiKey}`,
+        });
+    }
+    catch (err) {
+        console.error("Error fetching bank accounts:", err);
+        throw err;
+    }
+};

package/dist/lib/getBanks.d.ts

@@ -0,0 +1,17 @@
+type BankType = {
+    id: string;
+    name: string;
+    country: string;
+};
+/**
+ * Fetches a list of banks from the public API endpoint.
+ * Returns an array of bank objects or throws an error if the request fails.
+ *
+ * Returns:
+ *   An array of objects, each containing id, name, and country of a bank.
+ *
+ * Raises:
+ *   Throws an error if the request fails.
+ */
+export declare const getBanks: () => Promise<BankType[]>;
+export {};

package/dist/lib/getBanks.js

@@ -0,0 +1,20 @@
+import { get } from '../utils/api.js';
+/**
+ * Fetches a list of banks from the public API endpoint.
+ * Returns an array of bank objects or throws an error if the request fails.
+ *
+ * Returns:
+ *   An array of objects, each containing id, name, and country of a bank.
+ *
+ * Raises:
+ *   Throws an error if the request fails.
+ */
+export const getBanks = async () => {
+    try {
+        return await get(`/pub/bank`);
+    }
+    catch (err) {
+        console.error('Error fetching Banks:', err);
+        throw err;
+    }
+};

package/dist/lib/getRate.d.ts

@@ -0,0 +1,26 @@
+type RateType = {
+    baseCurrency: string;
+    targetCurrency: string;
+    rate: number;
+    amounts: {
+        userTax: number;
+        merchantTax: number;
+        amountUSD: number;
+        userAmountFiat: number;
+    };
+};
+/**
+ * Fetches the exchange rate and related amounts for a given amount from the public API.
+ * Returns an object containing currency information, rate, and detailed amounts, or throws an error if the request fails.
+ *
+ * Args:
+ *   amount: The amount for which to fetch the rate. If not provided or falsy, fetches the default rate.
+ *
+ * Returns:
+ *   An object with baseCurrency, targetCurrency, rate, and amounts (userTax, merchantTax, amountUSD, userAmountFiat).
+ *
+ * Raises:
+ *   Throws an error if the request fails.
+ */
+export declare const getRate: (amount: number) => Promise<RateType>;
+export {};

package/dist/lib/getRate.js

@@ -0,0 +1,23 @@
+import { get } from '../utils/api.js';
+/**
+ * Fetches the exchange rate and related amounts for a given amount from the public API.
+ * Returns an object containing currency information, rate, and detailed amounts, or throws an error if the request fails.
+ *
+ * Args:
+ *   amount: The amount for which to fetch the rate. If not provided or falsy, fetches the default rate.
+ *
+ * Returns:
+ *   An object with baseCurrency, targetCurrency, rate, and amounts (userTax, merchantTax, amountUSD, userAmountFiat).
+ *
+ * Raises:
+ *   Throws an error if the request fails.
+ */
+export const getRate = async (amount) => {
+    try {
+        return await get(amount ? `/pub/rate/${amount}` : '/pub/rate');
+    }
+    catch (err) {
+        console.error('Error fetching Rate:', err);
+        throw err;
+    }
+};

package/dist/lib/getTXPoolAddress.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Fetches the transaction pool address from the public API endpoint.
+ * Returns the address as a string or throws an error if the request fails.
+ *
+ * Returns:
+ *   The transaction pool address as a string.
+ *
+ * Raises:
+ *   Throws an error if the request fails.
+ */
+export declare const getTXPoolAddress: () => Promise<{
+    address: string;
+}>;

package/dist/lib/getTXPoolAddress.js

@@ -0,0 +1,20 @@
+import { get } from '../utils/api.js';
+/**
+ * Fetches the transaction pool address from the public API endpoint.
+ * Returns the address as a string or throws an error if the request fails.
+ *
+ * Returns:
+ *   The transaction pool address as a string.
+ *
+ * Raises:
+ *   Throws an error if the request fails.
+ */
+export const getTXPoolAddress = async () => {
+    try {
+        return await get('/pub/txpool-address');
+    }
+    catch (err) {
+        console.error('Error fetching TX Pool Address:', err);
+        throw err;
+    }
+};

package/dist/lib/getWallet.d.ts

@@ -0,0 +1,24 @@
+export type WalletType = {
+    id: string;
+    publicKey: string;
+    bankAccount: {
+        id: string;
+        accountName: string;
+        accountNumber: string;
+        bank: string;
+    };
+};
+/**
+ * Fetches wallet details for a given public key from the public API endpoint.
+ * Returns the wallet information including bank account details or throws an error if the request fails.
+ *
+ * Args:
+ *   publicKey: The public key of the wallet to fetch.
+ *
+ * Returns:
+ *   An object containing wallet id, publicKey, and associated bank account details.
+ *
+ * Raises:
+ *   Throws an error if the request fails.
+ */
+export declare const getWallet: (publicKey: string) => Promise<WalletType>;

package/dist/lib/getWallet.js

@@ -0,0 +1,23 @@
+import { get } from '../utils/api.js';
+/**
+ * Fetches wallet details for a given public key from the public API endpoint.
+ * Returns the wallet information including bank account details or throws an error if the request fails.
+ *
+ * Args:
+ *   publicKey: The public key of the wallet to fetch.
+ *
+ * Returns:
+ *   An object containing wallet id, publicKey, and associated bank account details.
+ *
+ * Raises:
+ *   Throws an error if the request fails.
+ */
+export const getWallet = async (publicKey) => {
+    try {
+        return await get(`/pub/wallet/${publicKey}`);
+    }
+    catch (err) {
+        console.error('Error fetching wallet:', err);
+        throw err;
+    }
+};

package/dist/lib/initiate.d.ts

@@ -0,0 +1,18 @@
+type InitiateResponse = {
+    email: string;
+};
+/**
+ * Initiates a process by sending the provided email to the public API endpoint.
+ * Returns the response from the API or throws an error if the request fails.
+ *
+ * Args:
+ *   email: The email address to send in the initiation request.
+ *
+ * Returns:
+ *   The response data from the API.
+ *
+ * Raises:
+ *   Throws an error if the request fails.
+ */
+export declare const initiate: (email: string) => Promise<InitiateResponse>;
+export {};

package/dist/lib/initiate.js

@@ -0,0 +1,23 @@
+import { post } from '../utils/api.js';
+/**
+ * Initiates a process by sending the provided email to the public API endpoint.
+ * Returns the response from the API or throws an error if the request fails.
+ *
+ * Args:
+ *   email: The email address to send in the initiation request.
+ *
+ * Returns:
+ *   The response data from the API.
+ *
+ * Raises:
+ *   Throws an error if the request fails.
+ */
+export const initiate = async (email) => {
+    try {
+        return await post('/pub/initiate', { email }, { 'x-api-key': '3ada687e-78d1-45f3-933d-c992adcc2bbb' });
+    }
+    catch (err) {
+        console.error('Error initiating:', err);
+        throw err;
+    }
+};

package/dist/lib/resolveBankAccount.d.ts

@@ -0,0 +1,26 @@
+type ResolveBankAccountType = {
+    accountName: string;
+    accountNumber: string;
+    bank: {
+        id: string;
+        name: string;
+        code: string;
+        country: string;
+    };
+};
+/**
+ * Resolves and fetches bank account details for a given bank ID and account number from the public API.
+ * Returns the account name, account number, and bank details or throws an error if the request fails.
+ *
+ * Args:
+ *   bankId: The ID of the bank.
+ *   accountNumber: The bank account number to resolve.
+ *
+ * Returns:
+ *   An object containing accountName, accountNumber, and bank details (id, name, code, country).
+ *
+ * Raises:
+ *   Throws an error if the request fails.
+ */
+export declare const resolveBankAccount: (bankId: string, accountNumber: string) => Promise<ResolveBankAccountType>;
+export {};