paj_ramp 1.3.2 → 1.4.1

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, Environment } from 'paj_ramp';
 
 // Selects the environment you want to work with
-initializeSDK('staging'); // or production
+initializeSDK(Environment.Production); // or Environment.Staging
 ```
 
 ### Initiate Session
@@ -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:
@@ -216,7 +234,7 @@ amount: number;
 usdcAmount: number;
 fiatAmount: number;
 sender: string;
-receipiant: string;
+receipient: string;
 rate: number;
 status: TransactionStatus;
 transactionType: TransactionType;
@@ -242,7 +260,7 @@ amount: number;
 usdcAmount: number;
 fiatAmount: number;
 sender: string;
-receipiant: string;
+receipint: string;
 rate: number;
 status: TransactionStatus;
 transactionType: TransactionType;
@@ -255,31 +273,31 @@ createdAt: string | Date;
 ### Usage Example
 
 ```typescript
-import { offRampCreateOrder } from 'paj_ramp';
+import { createOfframpOrder, Currency } from 'paj_ramp';
 
-const createOrder = await offRampCreateOrder(
-  'token',
-  'bank_id',
-  'account_number',
-  'NGN', // Currency
-  10000, // amount
-  'token_mint_address'
-  'webhook_url'
+const createOrder = await createOfframpOrder(
+  {
+    bank: 'bank_id',
+    accountNumber: 'account_number',
+    currency: 'NGN' as Currency, // Currency
+    amount: 10000, // amount
+    mint: 'token_mint_address',
+    webhookURL: 'webhook_url', // https://your-domain.com/webhook
+  },
+  'token'
 );
 /* Response: {
 id: string,
 address: string,
-signature?: string,
 mint: string,
 currency: Currency,
 amount: number,
-usdcAmount: number,
 fiatAmount: number,
 sender: string,
-receipiant: string,
 rate: number,
 status: TransactionStatus,
 transactionType: TransactionType
+createdAt: string
 }*/
 ```
 
@@ -288,17 +306,19 @@ transactionType: TransactionType
 ### Usage Example
 
 ```typescript
-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',
-});
+import { createOrder, Currency } from 'paj_ramp';
+
+const order = await createOrder(
+  {
+    fiatAmount: 10000,
+    currency: 'NGN' as Currency,
+    recipient: 'wallet_address_here',
+    mint: 'token_mint_address_here',
+    chain: 'SOLANA', //ethereum, polygon, etc
+    webhookURL: 'your_webhook_url', // https://your-domain.com/webhook
+  },
+  'token_from_verification'
+);
 // Response: { id: string, accountNumber: string, accountName: string, fiatAmount: number, bank: string }
 ```
 
@@ -317,194 +337,319 @@ 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
 }
 ```
 
-## Other types
+## SDK Reference
+
+### Complete On-Ramp Flow Example
 
 ```typescript
 import {
-  // Chain, // SOLANA, etc
-  TransactionStatus, // INIT, etc
-  TransactionType, // ON_RAMP, etc
-  Currency, // NGN
+  initializeSDK,
+  initiate,
+  verify,
+  createOnrampOrder,
+  getTransaction,
+  getAllTransactions,
+  Environment,
 } from 'paj_ramp';
-```
-
-<!--
-## Quick Start
+import dotenv from 'dotenv';
 
-### Real-time Order Observation
+dotenv.config();
 
-The SDK provides Socket.IO functionality to observe onramp orders in real-time:
+async function main() {
+  // Step 1: Initialize SDK
+  console.log('🚀 Initializing PAJ Ramp SDK...');
+  initializeSDK(Environment.Local);
 
-```typescript
-import { observeOrder } from 'paj_ramp';
-
-// Using observeOrder function
-const observer = observeOrder({
-  orderId: 'your_order_id',
-  onOrderUpdate: data => {
-    console.log('Order update:', data);
-    // Handle status changes: pending, processing, completed, failed, cancelled
-  },
-  onError: error => {
-    console.error('Socket error:', error);
-  },
-});
+  const email = process.env.USER_EMAIL!;
+  const apiKey = process.env.BUSINESS_API_KEY!;
+  const fiatAmount = parseInt(process.env.FIAT_AMOUNT!);
+  const currency = process.env.CURRENCY!;
+  const recipient = process.env.WALLET_ADDRESS!;
+  const mint = process.env.TOKEN_MINT!;
+  const webhookURL = process.env.WEBHOOK_URL!;
 
-await observer.connect();
-```
+  try {
+    // Step 2: Initiate session
+    console.log('\n📧 Initiating session...');
+    console.log('Email:', email);
+    console.log('API Key:', apiKey);
+    const initiated = await initiate(email, apiKey);
+    console.log('✅ OTP sent to:', initiated.email || initiated.phone);
+
+    // In a real application, you would wait for the user to receive and enter the OTP
+    // For this example, we assume you have the OTP from your email
+    console.log(
+      '\n⏳ Please check your email for the OTP and add it to your .env file'
+    );
+
+    const otp = process.env.OTP;
+    if (!otp) {
+      console.error(
+        '❌ OTP not found in .env file. Please add OTP=your_otp to .env'
+      );
+      process.exit(1);
+    }
 
-### Order Update Data Structure
+    // Step 3: Verify session
+    console.log('\n🔐 Verifying session with OTP...');
+    const verified = await verify(
+      email,
+      otp,
+      {
+        uuid: 'example-device-uuid-' + Date.now(),
+        device: 'Desktop',
+        os: 'MacOS',
+        browser: 'Chrome',
+      },
+      apiKey
+    );
+    console.log('✅ Session verified successfully!');
+    console.log(
+      'Token (first 20 chars):',
+      verified.token.substring(0, 20) + '...'
+    );
+
+    const sessionToken = verified.token;
+
+    // Step 4: Create onramp order
+    console.log('\n💰 Creating onramp order...');
+    const order = await createOnrampOrder(
+      {
+        fiatAmount,
+        currency,
+        recipient,
+        mint,
+        chain: 'SOLANA',
+        webhookURL,
+      },
+      sessionToken
+    );
+
+    console.log('\n✅ Order created successfully!');
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log('📋 Order Details:');
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log('Order ID:', order.id);
+    console.log('Account Number:', order.accountNumber);
+    console.log('Account Name:', order.accountName);
+    console.log(
+      'Fiat Amount (to send):',
+      order.fiatAmount,
+      process.env.CURRENCY
+    );
+    console.log('Token Amount (to receive):', order.amount);
+    console.log('Bank:', order.bank);
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+
+    // Step 5: Fetch the transaction details
+    console.log('\n🔍 Fetching transaction details...');
+    const transaction = await getTransaction(sessionToken, order.id);
+
+    console.log('\n✅ Transaction fetched successfully!');
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log('📋 Transaction Details:');
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log('Transaction ID:', transaction.id);
+    console.log('Status:', transaction.status);
+    console.log('Type:', transaction.transactionType);
+    console.log('Mint:', transaction.mint);
+    console.log('Currency:', transaction.currency);
+    console.log('Token Amount:', transaction.amount);
+    console.log('USDC Amount:', transaction.usdcAmount);
+    console.log('Fiat Amount:', transaction.fiatAmount);
+    console.log('Rate:', transaction.rate);
+    console.log('Recipient:', transaction.recipient);
+    console.log('Created At:', transaction.createdAt);
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+
+    // Step 6: Fetch all transactions
+    console.log('\n📜 Fetching all transactions...');
+    const allTransactions = await getAllTransactions(sessionToken);
+
+    console.log(`\n✅ Found ${allTransactions.length} transaction(s)!\n`);
+
+    if (allTransactions.length > 0) {
+      console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+      console.log('📋 All Transactions:');
+      console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+
+      allTransactions.forEach((tx, index) => {
+        console.log(`\n${index + 1}. Transaction ID: ${tx.id}`);
+        console.log(`   Status: ${tx.status}`);
+        console.log(`   Type: ${tx.transactionType}`);
+        console.log(`   Amount: ${tx.amount} (${tx.currency})`);
+        console.log(`   Fiat: ${tx.fiatAmount}`);
+        console.log(`   Created: ${tx.createdAt}`);
+      });
+
+      console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    }
 
-```typescript
-interface OnRampOrderUpdate {
-  id: string;
-  fiatAmount: string;
-  currency: string;
-  recipient: string; // wallet address
-  mint: string; // token address
-  chain: Chain; // enum: 'solana', 'ethereum', 'polygon'
-  status: OnRampStatus; // enum: 'pending', 'processing', 'completed', 'failed', 'cancelled'
+    console.log('\n📝 Next Steps:');
+    console.log(
+      '1. Transfer',
+      order.fiatAmount,
+      process.env.CURRENCY,
+      'to the account number above'
+    );
+    console.log('2. Your webhook will receive status updates');
+    console.log('3. Once payment is confirmed, you will receive tokens');
+  } catch (error) {
+    console.error(
+      '\n❌ Error:',
+      error instanceof Error ? error.message : String(error)
+    );
+    if (error && typeof error === 'object' && 'response' in error) {
+      console.error('Response data:', (error as any).response.data);
+    }
+    process.exit(1);
+  }
 }
-```
-
-### Socket Events
-
-The SDK listens for these Socket.IO events:
-
-- **ORDER_UPDATE**: Real-time order status updates
-- **ERROR**: Error messages from the server
-
-## API Reference
-
-### observeOrder(options)
 
-Creates an order observer.
-
-**Parameters:**
-
-- `options.orderId` (string, required): The order ID to observe
-- `options.onOrderUpdate` (function, optional): Callback for order updates
-- `options.onError` (function, optional): Callback for errors
-- `options.onConnect` (function, optional): Callback when connected
-- `options.onDisconnect` (function, optional): Callback when disconnected
-- `options.onConnectionStatusChange` (function, optional): Callback for connection status changes
-
-**Returns:**
-
-- `socket`: The Socket.IO instance
-- `isConnected()`: Function to check connection status
-- `connect()`: Function to connect to the socket
-- `disconnect()`: Function to disconnect from the socket
-
-**Example:**
-
-```typescript
-import { observeOrder } from 'paj_ramp';
-
-const observer = observeOrder({
-  orderId: 'your_order_id',
-  onOrderUpdate: data => console.log(data),
-});
-
-// Connect manually
-await observer.connect();
-
-// Check connection status
-console.log('Connected:', observer.isConnected());
-
-// Disconnect manually: you could use setTimeout to keep the socket alive for a certain amount of time before you disconnect
-observer.disconnect();
+main();
 ```
 
-## Error Handling
-
-The SDK provides comprehensive error handling:
+### Complete Off-Ramp Flow Example
 
 ```typescript
-const observer = observeOrder({
-  orderId: 'your_order_id',
-  onError: error => {
-    // Handle connection errors, order not found, etc.
-    console.error('Socket error:', error);
-  },
-});
-```
+import {
+  initializeSDK,
+  initiate,
+  verify,
+  getBanks,
+  createOfframpOrder,
+  Currency,
+  Environment,
+} from 'paj_ramp';
+import dotenv from 'dotenv';
 
-Common error messages:
+dotenv.config();
 
-- `"Order not found: {orderId}"`
-- `"Connection failed"`
-- `"Socket timeout"`
+async function main() {
+  // Step 1: Initialize SDK
+  console.log('🚀 Initializing PAJ Ramp SDK...');
+  initializeSDK(Environment.Local);
 
-### Usage Example
+  const email = process.env.USER_EMAIL!;
+  const apiKey = process.env.BUSINESS_API_KEY!;
+  const accountNumber = process.env.ACCOUNT_NUMBER!;
+  const bankId = process.env.BANK_ID!;
+  const currency = process.env.CURRENCY! as Currency;
+  const mint = process.env.TOKEN_MINT!;
+  const webhookURL = process.env.WEBHOOK_URL!;
 
-```typescript
-import { observeOrder, createOrder } from 'paj_ramp';
-
-async function example(orderId) {
-  console.log('Observe Order');
-
-  const observer = observeOrder({
-    orderId,
-    onOrderUpdate: data => {
-      console.log('Order update received:', data);
-      console.log('Status:', data.status);
-      console.log('Amount:', data.amount);
-      console.log('Currency:', data.currency);
-    },
-    onError: error => {
-      console.error('Socket error:', error);
-    },
-    onConnect: () => {
-      console.log('Connected to order socket');
-    },
-    onDisconnect: () => {
-      console.log('Disconnected from order socket');
-    },
-    onConnectionStatusChange: connected => {
+  try {
+    // Step 2: Initiate session
+    console.log('\n📧 Initiating session...');
+    const initiated = await initiate(email, apiKey);
+    console.log('✅ OTP sent to:', initiated.email || initiated.phone);
+
+    const otp = process.env.OTP;
+    if (!otp) {
+      console.error(
+        '❌ OTP not found in .env file. Please add OTP=your_otp to .env'
+      );
+      process.exit(1);
+    }
+
+    // Step 3: Verify session
+    console.log('\n🔐 Verifying session with OTP...');
+    const verified = await verify(
+      email,
+      otp,
+      {
+        uuid: 'example-device-uuid-' + Date.now(),
+        device: 'Desktop',
+        os: 'MacOS',
+        browser: 'Chrome',
+      },
+      apiKey
+    );
+    console.log('✅ Session verified successfully!');
+
+    const sessionToken = verified.token;
+
+    // Step 4: Get available banks
+    console.log('\n🏦 Fetching available banks...');
+    const banks = await getBanks(sessionToken);
+    console.log(`✅ Found ${banks.length} banks`);
+    if (banks.length > 0) {
       console.log(
-        'Connection status changed:',
-        connected ? 'Connected' : 'Disconnected'
+        'First few banks:',
+        banks
+          .slice(0, 3)
+          .map(b => b.name)
+          .join(', ')
       );
-    },
-  });
+    }
 
-  try {
-    await observer.connect();
-    console.log('Successfully connected to order observer');
-
-    // Keep the connection alive for 1 minute
-    setTimeout(() => {
-      console.log('Disconnecting after 1 minute...');
-      observer.disconnect();
-    }, 1 * 60 * 1000);
+    // Step 7: Create offramp order
+    console.log('\n💸 Creating offramp order...');
+    const order = await createOfframpOrder(
+      {
+        token: verified.token,
+        bank: bankId,
+        accountNumber,
+        currency,
+        amount: parseInt(process.env.TOKEN_AMOUNT || '1'),
+        mint,
+        webhookURL,
+      },
+      sessionToken
+    );
+
+    console.log('\n✅ Offramp order created successfully!');
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log('📋 Order Details:');
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log('Order ID:', order.id);
+    console.log('Address:', order.address);
+    console.log('Mint:', order.mint);
+    console.log('Token Amount (to pay):', order.amount);
+    console.log('Fiat Amount (to receive):', order.fiatAmount);
+    console.log('Rate:', order.rate);
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+
+    console.log('\n📝 Next Steps:');
+    console.log('1. Send', order.amount, 'tokens to address:', order.address);
+    console.log('2. Your webhook will receive status updates');
+    console.log(
+      '3. Once tokens are received and confirmed, fiat will be sent to your bank account'
+    );
   } catch (error) {
-    console.error('Failed to connect:', error);
+    console.error(
+      '\n❌ Error:',
+      error instanceof Error ? error.message : String(error)
+    );
+    if (error && typeof error === 'object' && 'response' in error) {
+      console.error('Response data:', (error as any).response.data);
+    }
+    process.exit(1);
   }
 }
 
-const order = await createOrder({
-  fiatAmount: 10000,
-  currency: 'NGN',
-  recipient: 'your_wallet_address',
-  mint: 'your_token_mint_address',
-  chain: 'SOLANA',
-  webhookURL: 'webhook_url',
-  token: token_from_verification,
-});
-
-await example(order.id);
-// Response: { id: string, fiatAmount: string, currency: string, , recipient: string,  mint: string, chain: Chain, amount: number, status: OnRampStatus }
-``` -->
-
----
+main();
+```
+
+## Other types
+
+```typescript
+import {
+  // Chain, // SOLANA, etc
+  TransactionStatus, // INIT, etc
+  TransactionType, // ON_RAMP, etc
+  Currency, // NGN
+  Environment,
+  RateType,
+} from 'paj_ramp';
+```
 
 ## License
 

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/dist/lib/off_ramp/directCreateOrder.d.ts

@@ -1,19 +1,20 @@
-import { Currency, TransactionStatus, TransactionType } from '../../utils/enums.js';
-type offRampCreateOrderResponse = {
+import { Currency } from "../../utils/enums.js";
+interface CreateOfframpOrder {
+    bank: string;
+    accountNumber: string;
+    currency: Currency;
+    amount: number;
+    mint: string;
+    webhookURL: string;
+}
+export interface OfframpOrder {
     id: string;
     address: string;
-    signature?: string;
     mint: string;
     currency: Currency;
     amount: number;
-    usdcAmount: number;
     fiatAmount: number;
-    sender: string;
-    receipiant: string;
     rate: number;
-    status: TransactionStatus;
-    transactionType: TransactionType;
-    createdAt: string;
-};
-export declare const offRampCreateOrder: (token: string, bank: string, accountNumber: string, currency: string, amount: number, mint: string, webhookURL: string) => Promise<offRampCreateOrderResponse>;
+}
+export declare const createOfframpOrder: (order: CreateOfframpOrder, sessionToken: string) => Promise<OfframpOrder>;
 export {};