paj_ramp 1.3.2 → 1.4.0

package/README.md

@@ -17,10 +17,10 @@ yarn add paj_ramp
 ### Initialize SDK (select environment: "staging" | "production")
 
 ```typescript
-import { initializeSDK } from 'paj_ramp';
+import { initializeSDK } from "paj_ramp";
 
 // Selects the environment you want to work with
-initializeSDK('staging'); // or production
+initializeSDK("staging"); // or production
 ```
 
 ### Initiate Session
@@ -40,13 +40,13 @@ const initiated = await initiate(
 ### Verify Session
 
 ```typescript
-import { verify } from 'paj_ramp';
+import { verify } from "paj_ramp";
 
 // You can get otp by either adding your phone number or email address
 // Phone number must start with a country code
 const verified = await verify(
-  'your_email@gmail.com', // or +2349053231563
-  'otp',
+  "your_email@gmail.com", // or +2349053231563
+  "otp",
   {
     uuid: string,
     device: string,
@@ -55,7 +55,7 @@ const verified = await verify(
     browser: string, //chrome
     ip: string,
   },
-  'business_api_key'
+  "business_api_key"
 );
 /* Response: {
 email?: string,
@@ -66,6 +66,24 @@ token: string
 } */
 ```
 
+## 📚 Examples
+
+Check out our [examples directory](./examples) for complete, runnable examples:
+
+- **[Basic Onramp](./examples/basic-onramp)** - Simple onramp transaction flow showing how users can buy crypto with fiat
+- **[Basic Offramp](./examples/basic-offramp)** - Simple offramp transaction flow showing how users can sell crypto for fiat
+- **[Webhook Integration](./examples/webhook-integration)** - Express server with webhook handling for real-time order updates
+
+Each example includes its own README with detailed setup instructions. Perfect for understanding how to integrate PAJ Ramp into your application!
+
+```bash
+cd examples/basic-onramp
+npm install
+cp .env.example .env
+# Edit .env with your credentials
+npm start
+```
+
 ## Utility Endpoints
 
 ### Handle Rate:
@@ -73,7 +91,7 @@ token: string
 **_Get All Rate_**
 
 ```typescript
-import { getAllRate } from 'paj_ramp';
+import { getAllRate } from "paj_ramp";
 
 const rate = await getAllRate();
 /*
@@ -99,7 +117,7 @@ Response:
 **_Get Rate by Amount_**
 
 ```typescript
-import { getRateByAmount } from 'paj_ramp';
+import { getRateByAmount } from "paj_ramp";
 
 const rate = await getRateByAmount(50000);
 /*
@@ -122,7 +140,7 @@ Response:
 **_Get Rate by Rate Type_**
 
 ```typescript
-import { getRateByType, RateType } from 'paj_ramp';
+import { getRateByType, RateType } from "paj_ramp";
 
 const rate = await getRateByType(RateType.offRamp); // or RateType.onRamp
 
@@ -140,9 +158,9 @@ Response:
 **_Get Token Value from Amount and Mint Token_**
 
 ```typescript
-import { getTokenValue } from 'paj_ramp';
+import { getTokenValue } from "paj_ramp";
 
-const tokenValue = await getTokenValue(50000, 'token_mint_address');
+const tokenValue = await getTokenValue(50000, "token_mint_address");
 /*
 Response:
 {
@@ -158,21 +176,21 @@ Response:
 **_Get Banks_**
 
 ```typescript
-import { getBanks } from 'paj_ramp';
+import { getBanks } from "paj_ramp";
 
-const banks = await getBanks('token');
+const banks = await getBanks("token");
 // Response: [ { id: string, name: string, country: string } ]
 ```
 
 **_Resolve Bank Account_**
 
 ```typescript
-import { resolveBankAccount } from 'paj_ramp';
+import { resolveBankAccount } from "paj_ramp";
 
 const resolvedBankAccount = await resolveBankAccount(
-  'token',
-  'bank_id',
-  'account_number'
+  "token",
+  "bank_id",
+  "account_number"
 );
 // Response: { accountName: string, accountNumber: string, bank: { id: string, name: string, code: string, country: string } }
 ```
@@ -180,12 +198,12 @@ const resolvedBankAccount = await resolveBankAccount(
 **_Add Bank Account_**
 
 ```typescript
-import { addBankAccount } from 'paj_ramp';
+import { addBankAccount } from "paj_ramp";
 
 const addedBankAccount = await addBankAccount(
-  'token',
-  'bank_id',
-  'account_number'
+  "token",
+  "bank_id",
+  "account_number"
 );
 // Response: { id: string, accountName: string, accountNumber: string, bank: string }
 ```
@@ -193,9 +211,9 @@ const addedBankAccount = await addBankAccount(
 **_Get Bank Accounts_**
 
 ```typescript
-import { getBankAccounts } from 'paj_ramp';
+import { getBankAccounts } from "paj_ramp";
 
-const accounts = await getBankAccounts('token');
+const accounts = await getBankAccounts("token");
 // Response: [ { id: string, accountName: string, accountNumber: string, bank: string } ]
 ```
 
@@ -204,9 +222,9 @@ const accounts = await getBankAccounts('token');
 **_Get All Transactions_**
 
 ```typescript
-import { getAllTransactions } from 'paj_ramp';
+import { getAllTransactions } from "paj_ramp";
 
-const transactions = await getAllTransactions('token_from_verification');
+const transactions = await getAllTransactions("token_from_verification");
 /* Response: [{
 id: string;
 address: string;
@@ -216,7 +234,7 @@ amount: number;
 usdcAmount: number;
 fiatAmount: number;
 sender: string;
-receipiant: string;
+receipient: string;
 rate: number;
 status: TransactionStatus;
 transactionType: TransactionType;
@@ -227,11 +245,11 @@ createdAt: string | Date;
 **_Get Transaction_**
 
 ```typescript
-import { getTransaction } from 'paj_ramp';
+import { getTransaction } from "paj_ramp";
 
 const transactions = await getTransaction(
-  'token_from_verification',
-  'transaction_id'
+  "token_from_verification",
+  "transaction_id"
 );
 /* Response: {
 id: string;
@@ -242,7 +260,7 @@ amount: number;
 usdcAmount: number;
 fiatAmount: number;
 sender: string;
-receipiant: string;
+receipint: string;
 rate: number;
 status: TransactionStatus;
 transactionType: TransactionType;
@@ -276,7 +294,7 @@ amount: number,
 usdcAmount: number,
 fiatAmount: number,
 sender: string,
-receipiant: string,
+receipint: string,
 rate: number,
 status: TransactionStatus,
 transactionType: TransactionType
@@ -288,16 +306,16 @@ transactionType: TransactionType
 ### Usage Example
 
 ```typescript
-import { createOrder } from 'paj_ramp';
+import { createOrder } from "paj_ramp";
 
 const order = await createOrder({
   fiatAmount: 10000,
-  currency: 'NGN',
-  recipient: 'wallet_address_here',
-  mint: 'token_mint_address_here',
-  chain: 'SOLANA', //ethereum, polygon, etc
-  webhookURL: 'your_webhook_url',
-  token: 'token_from_verification',
+  currency: "NGN",
+  recipient: "wallet_address_here",
+  mint: "token_mint_address_here",
+  chain: "SOLANA", //ethereum, polygon, etc
+  webhookURL: "your_webhook_url",
+  token: "token_from_verification",
 });
 // Response: { id: string, accountNumber: string, accountName: string, fiatAmount: number, bank: string }
 ```
@@ -317,7 +335,7 @@ const order = await createOrder({
   usdcAmount: number;
   fiatAmount: number;
   sender: string;
-  receipiant: string;
+  receipient: string;
   rate: number;
   status: TransactionStatus; // eg. INIT, PAID, COMPLETED
   transactionType: TransactionType; // ON_RAMP or OFF_RAMP
@@ -332,7 +350,7 @@ import {
   TransactionStatus, // INIT, etc
   TransactionType, // ON_RAMP, etc
   Currency, // NGN
-} from 'paj_ramp';
+} from "paj_ramp";
 ```
 
 <!--

package/__tests__/session.test.ts

@@ -0,0 +1,38 @@
+import { initiate } from "../lib/utility/session/initiate";
+import { deviceSignatureType, verify } from "../lib/utility/session/verify";
+import * as api from "../utils/api";
+
+describe("Session", () => {
+  const mockEmail = "matthew.chukwuemeka@gmail.com";
+  const ApiKey = "ApiKey";
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it("should return session when API call succeeds", async () => {
+    jest.spyOn(api, "get").mockResolvedValue({ email: mockEmail });
+
+    const result = await initiate(mockEmail, ApiKey);
+    expect(result).toEqual({ email: mockEmail });
+  });
+
+  it("should throw an error when API call fails", async () => {
+    const error = new Error("API Failure");
+    jest.spyOn(api, "get").mockRejectedValue(error);
+
+    await expect(initiate(mockEmail, ApiKey)).rejects.toThrow("API Failure");
+  });
+
+  it("Should verify session when API call succeeds", async () => {
+    jest.spyOn(api, "get").mockResolvedValue({ email: mockEmail });
+
+    const device: deviceSignatureType = {
+      uuid: "uuid",
+      device: "device",
+      os: "os",
+    };
+    const result = await verify(mockEmail, "OTP", device, ApiKey);
+    expect(result).toEqual({ email: mockEmail });
+  });
+});

package/examples/README.md

@@ -0,0 +1,141 @@
+# PAJ Ramp SDK Examples
+
+This directory contains complete, runnable examples demonstrating how to use the PAJ Ramp SDK in real-world scenarios.
+
+## 📚 Available Examples
+
+### [Basic Onramp](./basic-onramp)
+
+**Difficulty:** Beginner  
+**What you'll learn:**
+
+- Session management (initiate & verify)
+- Creating onramp orders
+- Handling bank account details for payment
+
+Perfect for: Understanding the basic onramp flow where users buy crypto with fiat.
+
+---
+
+### [Basic Offramp](./basic-offramp)
+
+**Difficulty:** Beginner  
+**What you'll learn:**
+
+- Bank account verification and management
+- Creating offramp orders
+- Converting crypto to fiat
+
+Perfect for: Understanding the reverse flow where users sell crypto for fiat.
+
+---
+
+### [Webhook Integration](./webhook-integration)
+
+**Difficulty:** Intermediate  
+**What you'll learn:**
+
+- Setting up webhook endpoints
+- Handling order status updates in real-time
+- Building a REST API for order tracking
+- Production-ready webhook patterns
+
+Perfect for: Building production applications that need real-time order updates.
+
+---
+
+## 🚀 Quick Start
+
+Each example is self-contained with its own dependencies and README. To run any example:
+
+```bash
+cd examples/[example-name]
+npm install
+cp .env.example .env
+# Edit .env with your credentials
+npm start
+```
+
+## 📋 Prerequisites
+
+All examples require:
+
+- Node.js 16 or higher
+- A PAJ business API key ([Get one here](https://paj.cash))
+- Basic knowledge of JavaScript/Node.js
+
+Specific examples may have additional requirements (documented in their READMEs).
+
+## 🎯 Learning Path
+
+We recommend exploring the examples in this order:
+
+1. **Start with [Basic Onramp](./basic-onramp)**  
+   Understand the fundamental flow of creating onramp orders
+
+2. **Then try [Basic Offramp](./basic-offramp)**  
+   Learn the reverse process and bank account management
+
+3. **Finally explore [Webhook Integration](./webhook-integration)**  
+   Build production-ready integrations with real-time updates
+
+## 💡 Example Structure
+
+Each example follows this structure:
+
+```
+example-name/
+├── package.json          # Dependencies and scripts
+├── index.js (or server.js)  # Main application code
+├── .env.example          # Environment variables template
+└── README.md            # Detailed documentation
+```
+
+## 🔑 Getting Your API Key
+
+To run these examples, you'll need a PAJ business API key:
+
+1. Sign up at [paj.cash](https://paj.cash)
+2. Complete business verification
+3. Generate your API key from the dashboard
+4. Add it to each example's `.env` file
+
+## 🌍 Environment
+
+All examples support both staging and production environments:
+
+- **Staging**: For testing and development
+- **Production**: For live transactions
+
+Configure the environment in each example's `.env` file.
+
+## 🆘 Getting Help
+
+- 📖 Read the [main SDK documentation](../README.md)
+- 🐛 [Report issues](https://github.com/paj-cash/paj_ramp/issues)
+- 💬 [Join our Discord](https://discord.gg/pajcash) (if available)
+- 📧 Email: support@paj.cash
+
+## 🤝 Contributing
+
+Have an example you'd like to add? We welcome contributions!
+
+1. Fork the repository
+2. Create a new example following the existing structure
+3. Submit a pull request
+
+Good example ideas:
+
+- Next.js/React integration
+- Mobile app integration (React Native)
+- Advanced error handling patterns
+- Multi-currency support
+- Automated testing examples
+
+## 📄 License
+
+All examples are provided under the MIT License, same as the main SDK.
+
+---
+
+**Happy coding! 🎉**

package/examples/basic-offramp/.env.example

@@ -0,0 +1,24 @@
+# Get your API key from PAJ dashboard
+BUSINESS_API_KEY=e1f7b0c0-79f2-4912-ad60-efd46434db5a
+
+# User credentials
+USER_EMAIL=example@gmail.com
+
+# OTP from email (you'll receive this after running the script once)
+OTP=1112
+
+# Your bank details (where you want to receive fiat)
+BANK_ID=68781788c3ddffabdd90a96d
+ACCOUNT_NUMBER=0025635480
+
+# Token mint address (e.g., USDC on Solana)
+# USDC: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
+TOKEN_MINT=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
+TOKEN_AMOUNT=1
+
+# Your webhook URL (where you'll receive order status updates)
+WEBHOOK_URL=https://your-domain.com/webhook
+
+# Optional: Customize amount and currency
+FIAT_AMOUNT=3000
+CURRENCY=NGN

package/examples/basic-offramp/README.md

@@ -0,0 +1,186 @@
+# Basic Offramp Example
+
+This example demonstrates a complete offramp flow using the PAJ Ramp SDK, where a user can sell crypto tokens for fiat currency.
+
+## What This Example Shows
+
+- 🔧 Initializing the SDK
+- 📧 Session management (initiate and verify)
+- 🏦 Fetching available banks
+- 🔍 Resolving and verifying bank account details
+- ➕ Adding bank account to user profile
+- 💸 Creating an offramp order
+- 📋 Handling order details and next steps
+
+## Prerequisites
+
+- Node.js 16 or higher
+- A PAJ business API key
+- A valid email address or phone number
+- Your bank account details for receiving fiat
+- Crypto tokens to sell
+- A webhook endpoint (optional for testing)
+
+## Setup
+
+1. **Install dependencies:**
+
+   ```bash
+   npm install
+   ```
+
+2. **Copy the environment file:**
+
+   ```bash
+   cp .env.example .env
+   ```
+
+3. **Fill in your credentials in `.env`:**
+
+   - `BUSINESS_API_KEY`: Your PAJ business API key
+   - `USER_EMAIL`: Your email address
+   - `ACCOUNT_NUMBER`: Your bank account number
+
+4. **Run the example (first time to get OTP and see available banks):**
+
+   ```bash
+   npm start
+   ```
+
+5. **Add OTP and BANK_ID to `.env`:**
+   The script will show available banks. Copy the bank ID you want to use:
+
+   ```
+   OTP=123456
+   BANK_ID=your_bank_id_from_the_list
+   ```
+
+6. **Run again to complete the flow:**
+   ```bash
+   npm start
+   ```
+
+## Expected Output
+
+```
+🚀 Initializing PAJ Ramp SDK...
+
+📧 Initiating session...
+✅ OTP sent to: your_email@example.com
+
+🔐 Verifying session with OTP...
+✅ Session verified successfully!
+
+🏦 Fetching available banks...
+✅ Found 15 banks
+First few banks: GTBank, Access Bank, First Bank
+
+🔍 Resolving bank account...
+✅ Bank account verified!
+Account Name: John Doe
+Account Number: 1234567890
+Bank: GTBank
+
+➕ Adding bank account to profile...
+✅ Bank account added to profile
+Saved Account ID: abc123...
+
+💸 Creating offramp order...
+
+✅ Offramp order created successfully!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📋 Order Details:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Order ID: xyz789...
+Status: INIT
+Crypto Amount: 6.55
+USDC Amount: 6.55
+Fiat Amount: 10000 NGN
+Rate: 1525
+Recipient: 1234567890
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📝 Next Steps:
+1. Send 6.55 tokens to address: SoLxxx...
+2. Your webhook will receive status updates
+3. Once tokens are received and confirmed, fiat will be sent to your bank account
+```
+
+## How It Works
+
+### 1. SDK Initialization
+
+```javascript
+initializeSDK("staging"); // or 'production'
+```
+
+### 2. Session Management
+
+```javascript
+const initiated = await initiate(email, apiKey);
+const verified = await verify(email, otp, deviceInfo, apiKey);
+```
+
+### 3. Bank Account Setup
+
+```javascript
+// Get available banks
+const banks = await getBanks(token);
+
+// Verify account exists
+const resolved = await resolveBankAccount(token, bankId, accountNumber);
+
+// Save to profile
+const added = await addBankAccount(token, bankId, accountNumber);
+```
+
+### 4. Create Offramp Order
+
+```javascript
+const order = await offRampCreateOrder(
+  token,
+  bankAccountId,
+  accountNumber,
+  "NGN",
+  10000,
+  tokenMint,
+  webhookUrl
+);
+```
+
+### 5. Send Tokens
+
+Transfer the specified amount of tokens to the address provided in the order. The system will:
+
+- Detect the token transfer
+- Verify the transaction
+- Send updates to your webhook
+- Transfer fiat to your bank account
+
+## Next Steps
+
+- Check out the [webhook integration example](../webhook-integration) to see how to handle status updates
+- See the [basic onramp example](../basic-onramp) for the reverse flow
+- Read the [main documentation](../../README.md) for all available features
+
+## Troubleshooting
+
+### "OTP not found in .env file"
+
+Run the script once without OTP to receive it via email, then add it to `.env`.
+
+### "BANK_ID and ACCOUNT_NUMBER are required"
+
+The script will list available banks. Choose one and add its ID to `.env`.
+
+### "Bank account not found"
+
+Verify that your account number is correct and belongs to the selected bank.
+
+### "Invalid API key"
+
+Ensure your `BUSINESS_API_KEY` is correct and active.
+
+## Support
+
+For issues or questions, please visit the [GitHub repository](https://github.com/paj-cash/paj_ramp).