paj_ramp 1.0.0 → 1.1.1

package/README.md

@@ -1,254 +1,380 @@
-# paj_ramp
+# PAJ Ramp SDK
 
-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 comprehensive SDK for PAJ Ramp onramp and offramp operations with real-time transaction updates using Socket.IO.
 
-> _A simple wrapper for communicating with paj_ramp's backend endpoints — no manual API calls required._
+## Features
 
-### _“Send SOL. Get Naira.”_
+- **Onramp Operations**: Create orders and observe real-time updates
+- **Offramp Operations**: Complete offramp workflow with bank account management
+- **Real-time Updates**: Socket.IO integration for live transaction status updates
+- **TypeScript Support**: Full TypeScript definitions included
+- **Functional API**: Clean functional approach for better composability
 
-> _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._
+## Installation
+
+```bash
+npm install paj-ramp
+```
+
+```bash
+yarn add paj-ramp
+```
 
 ---
 
-## 🚀 Features
+# Onramp SDK (Real-time Order Observation)
 
-- ✅ 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
+## Quick Start
 
----
+### Real-time Order Observation
 
-## 📦 Installation
+The SDK provides Socket.IO functionality to observe onramp orders in real-time:
 
-```bash
-# With npm
-npm install paj_ramp
+```typescript
+import {
+  observeOrder,
+  createOrderObserver,
+  createOnRampSocket,
+} 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);
+  },
+});
 
-# With yarn
-yarn add paj_ramp
+await observer.connect();
 ```
 
----
+### Order Update Data Structure
+
+```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'
+}
+```
 
-## 📘 Usage Examples
+### Socket Events
 
-### Get tx pool address
+The SDK listens for these Socket.IO events:
 
-```bash
-import { getTXPoolAddress } from 'paj_ramp';
+- **ORDER_UPDATE**: Real-time order status updates
+- **ERROR**: Error messages from the server
 
-const txpooladdress = await getTXPoolAddress();
+## API Reference
 
-# Response
-{
-  address: string,
-}
+### 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();
 ```
 
-### Get rate
+## Error Handling
 
-```bash
-import { getRate } from 'paj_ramp';
+The SDK provides comprehensive error handling:
 
-const rate = await getRate();
+```typescript
+const observer = observeOrder({
+  orderId: "your_order_id",
+  onError: (error) => {
+    // Handle connection errors, order not found, etc.
+    console.error("Socket error:", error);
+  },
+});
+```
+
+Common error messages:
+
+- `"Order not found: {orderId}"`
+- `"Connection failed"`
+- `"Socket timeout"`
+
+### createOrder(orderData)
+
+Creates a new onramp order.
+
+**Parameters:**
+
+- `orderData` (object, required): Order creation data
+- `orderData.fiatAmount` (number, required): Order amount
+- `orderData.currency` (string, required): Currency code (e.g., 'USD', 'NGN')
+- `orderData.recipient` (string, required): Wallet address to receive tokens
+- `orderData.mint` (string, required): Token mint address
+- `orderData.chain` (Chain, required): Blockchain network ('solana', 'ethereum', 'polygon')
+- `orderData.token` (string, required): Verification token
+
+**Returns:**
 
-# Response
-{
-  baseCurrency: string,
-  targetCurrency: string,
-  rate: number
+- `id` (string): Unique order identifier
+- `accountNumber` (string): Bank account number for payment
+- `accountName` (string): Bank account holder name
+- `fiatAmount` (number): Order amount in fiat currency
+- `bank` (string): Bank name
+
+**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",
+  token: "token_from_verification",
+});
+// Response: { id: string, accountNumber: string, accountName: string, fiatAmount: number, bank: string }
+```
+
+### Usage Example
+
+```typescript
+import { observeOrder } 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) => {
+      console.log(
+        "Connection status changed:",
+        connected ? "Connected" : "Disconnected"
+      );
+    },
+  });
+
+  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);
+  } catch (error) {
+    console.error("Failed to connect:", error);
+  }
 }
+
+const order = await createOrder({
+  fiatAmount: 10000,
+  currency: "NGN",
+  recipient: "your_wallet_address",
+  mint: "your_token_mint_address",
+  chain: "SOLANA",
+  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 }
 ```
 
-### Get rate with amount
+---
 
-```bash
-import { getRate } from 'paj_ramp';
+# Offramp SDK
 
-const rate = await getRate(50000);
+## Overview
 
-# Response
-{
-  rate: {
-    baseCurrency: string,
-    targetCurrency: string,
-    rate: number
-  },
-  amounts: {
-    userTax: number,
-    merchantTax": number,
-    amountUSD": number,
-    userAmountFiat": number
-   }
-}
+The Offramp SDK provides a set of functions to help users convert Solana-based digital assets to fiat and transfer the resulting funds to traditional bank accounts. It includes session management, rate queries, bank account management, and wallet operations.
+
+## Usage Examples
+
+### Get TX Pool Address
+
+```typescript
+import { getTXPoolAddress } from "paj-ramp";
+
+const txpooladdress = await getTXPoolAddress();
+// Response: { address: string }
 ```
 
-### Initiate Session
+### Get Rate
 
-```bash
-import { initiate } from 'paj_ramp';
+```typescript
+import { getRate } from "paj-ramp";
 
-const initialized = await initiate('your_email@gmail.com');
+const rate = await getRate();
+// Response: { baseCurrency: string, targetCurrency: string, rate: number }
+```
 
-# Response
-{
-  email: string
-}
+### Get Rate with Amount
+
+```typescript
+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 }
+// }
 ```
 
-### Verify Session
+### Initiate Session
 
-```bash
-import { verify } from 'paj_ramp';
+```typescript
+import { initiate } from "paj-ramp";
 
-const verified = await verify('your_email@gmail.com', '1234', 'device signature');
+const initialized = await initiate("your_email@gmail.com");
+// Response: { email: string }
+```
 
-# Response
-{
-  email: string,
-  isActive: string,
-  expiresAt: string,
-  token: string
-}
+### Verify Session
+
+```typescript
+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
+### Get Banks
 
-```bash
-import { getBanks } from 'paj_ramp';
+```typescript
+import { getBanks } from "paj-ramp";
 
 const banks = await getBanks();
-
-# Response
-[
-  {
-    id: string,
-    name: string,
-    country: string
-  }
-]
+// 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,
-  }
-}
+```typescript
+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';
+```typescript
+import { addBankAccount } from "paj-ramp";
 
-const addedBankAccount = await addBankAccount('token', 'bank id', 'account number');
-
-# Response
-{
-  id: string,
-  accountName: string,
-  accountNumber: string,
-  bank: string
-}
+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';
+```typescript
+import { getBankAccounts } from "paj-ramp";
 
-const addedBankAccount = await getBankAccounts('token');
-
-# Response
-[
-  {
-    id: string,
-    accountName: string,
-    accountNumber: string,
-    bank: string
-  }
-]
+const accounts = 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
-  }
-}
+```typescript
+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
-  }
-}
+```typescript
+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
-  }
-}
-```
+```typescript
+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
+## License
 
-Your Name — Gospel Chidiebube Chukwu
+MIT
 
+## 🧑‍💻 Author
 
+Gospel Chidiebube Chukwu

package/dist/index.d.ts

@@ -1,11 +1,13 @@
-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';
+export { getTXPoolAddress } from "./lib/off_ramp/getTXPoolAddress.js";
+export { getRate } from "./lib/off_ramp/getRate.js";
+export { initiate } from "./lib/off_ramp/initiate.js";
+export { verify } from "./lib/off_ramp/verify.js";
+export { getBanks } from "./lib/off_ramp/getBanks.js";
+export { resolveBankAccount } from "./lib/off_ramp/resolveBankAccount.js";
+export { addBankAccount } from "./lib/off_ramp/addBankAccount.js";
+export { getBankAccounts } from "./lib/off_ramp/getBankAccounts.js";
+export { getWallet } from "./lib/off_ramp/getWallet.js";
+export { addWallet } from "./lib/off_ramp/addWallet.js";
+export { switchWalletBankAccount } from "./lib/off_ramp/switchWalletBankAccount.js";
+export { createOrder } from "./lib/on_ramp/createOrder.js";
+export { observeOrder, OnRampOrderUpdate } from "./lib/on_ramp/observeOrder.js";

package/dist/index.js

@@ -1,16 +1,21 @@
 //Web3.js - A JavaScript library for interacting with the Web3 ecosystem.
+//OFF RAMP
 //Wallet Info
-export { getTXPoolAddress } from './lib/getTXPoolAddress.js';
-export { getRate } from './lib/getRate.js';
+export { getTXPoolAddress } from "./lib/off_ramp/getTXPoolAddress.js";
+export { getRate } from "./lib/off_ramp/getRate.js";
 //Session Management
-export { initiate } from './lib/initiate.js';
-export { verify } from './lib/verify.js';
+export { initiate } from "./lib/off_ramp/initiate.js";
+export { verify } from "./lib/off_ramp/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';
+export { getBanks } from "./lib/off_ramp/getBanks.js";
+export { resolveBankAccount } from "./lib/off_ramp/resolveBankAccount.js";
+export { addBankAccount } from "./lib/off_ramp/addBankAccount.js";
+export { getBankAccounts } from "./lib/off_ramp/getBankAccounts.js";
 //Wallet Operations
-export { getWallet } from './lib/getWallet.js';
-export { addWallet } from './lib/addWallet.js';
-export { switchWalletBankAccount } from './lib/switchWalletBankAccount.js';
+export { getWallet } from "./lib/off_ramp/getWallet.js";
+export { addWallet } from "./lib/off_ramp/addWallet.js";
+export { switchWalletBankAccount } from "./lib/off_ramp/switchWalletBankAccount.js";
+// ON RAMP
+export { createOrder } from "./lib/on_ramp/createOrder.js";
+// NEW: Socket.IO exports
+export { observeOrder } from "./lib/on_ramp/observeOrder.js";

package/dist/lib/{addBankAccount.d.ts → off_ramp/addBankAccount.d.ts}

@@ -1,3 +1,9 @@
+type AddBankAccountType = {
+    id: string;
+    accountName: string;
+    accountNumber: string;
+    bank: string;
+};
 /**
  * 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.
@@ -13,9 +19,5 @@
  * 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;
-}>;
+export declare const addBankAccount: (token: string, bankId: string, accountNumber: string) => Promise<AddBankAccountType>;
+export {};

package/dist/lib/{addBankAccount.js → off_ramp/addBankAccount.js}

@@ -1,4 +1,4 @@
-import { post } from '../utils/api.js';
+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.
@@ -16,7 +16,7 @@ import { post } from '../utils/api.js';
  */
 export const addBankAccount = async (token, bankId, accountNumber) => {
     try {
-        return await post('/pub/bankAccount', {
+        return await post("/pub/bankAccount", {
             bankId,
             accountNumber,
         }, {
@@ -24,7 +24,7 @@ export const addBankAccount = async (token, bankId, accountNumber) => {
         });
     }
     catch (err) {
-        console.error('Error adding bank account:', err);
+        console.error("Error adding bank account:", err);
         throw err;
     }
 };

package/dist/lib/{addWallet.d.ts → off_ramp/addWallet.d.ts}

@@ -1,3 +1,4 @@
+import { WalletType } from "./getWallet.js";
 /**
  * Adds a new wallet for the user.
  * Returns the added wallet object or throws an error if the request fails.
@@ -8,4 +9,4 @@
  * 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>;
+export declare const addWallet: (apiKey: string, accountId: string, secretKey: Uint8Array) => Promise<WalletType>;