Esca SDK

A modern, type-safe TypeScript SDK for Esca Finance.

Installation

npm install esca-sdk
# or
bun add esca-sdk

Usage

Initialize the SDK

import { Esca } from 'esca-sdk';

const esca = new Esca({
  apiKey: 'esca_live_...',
  environment: 'production', // 'sandbox' or 'production'
  timeout: 30000,  // default: 30 seconds
  maxRetries: 3,   // default: 3 retries for 5xx and 429 errors
  logger: console, // optional pluggable logger
});

Virtual Accounts

// Create a virtual account
const [account] = await esca.accounts.create({
  currency: 'USD',
  email: '[email protected]',
  externalReference: 'ref_123'
});

// List virtual accounts
const accounts = await esca.accounts.list({ currency: 'USD' });

// Initiate a transfer from a virtual account
const transfer = await esca.accounts.initiateTransfer({
  accountId: 123,
  amount: 1000,
  currency: 'NGN',
  destinationBankCode: '058',
  destinationAccountNumber: '0123456789',
  destinationAccountName: 'John Doe',
  description: 'Payment for goods'
});

Auto-Pagination

For list endpoints that support pagination, the SDK provides an async iterator to automatically fetch all pages.

for await (const transaction of esca.accounts.transactionsAutoPaging({ accountId: 123 })) {
  console.log(transaction.amount, transaction.type);
}

Payouts (Transfers)

// Fiat Payout (International USD)
const payout = await esca.payouts.fiatPayout({
  amount: 100,
  currency: 'USD',
  countryCode: 'US',
  bankName: 'Chase Bank',
  bankCode: '021000021',
  accountNumber: '0123456789',
  beneficiaryType: 'INDIVIDUAL',
  firstName: 'John',
  lastName: 'Doe',
  streetAddress: '123 Main St',
  city: 'New York',
  postalCode: '100001',
  beneficiaryRelationship: 'OTHER'
});

// Crypto Payout (USDT ERC20)
const cryptoPayout = await esca.payouts.cryptoPayout({
  amount: 12,
  currency: 'USDT',
  protocol: 'ERC20',
  address: '0x6d32057a45C3CC68e3dFCF5Dde125AC65f913b2E',
  beneficiaryName: 'John Doe'
});

Conversions (FX)

// Example 1: NGN to GBP (Minimum 150,000 NGN) but GBP100 is around 1,880 as at time of writing
const ngnQuote = await esca.conversions.createQuote({
  sourceCurrency: 'NGN',
  targetCurrency: 'GBP',
  amount: 188_000,
});

const ngnConversion = await esca.conversions.convert({
  amount: 188_000,
  sourceCurrency: 'NGN',
  targetCurrency: 'GBP',
  quoteId: ngnQuote.quoteId
});

// Example 1: NGN to EUR (Minimum 150,000 NGN) but EUR100 is around 1,650 as at time of writing
const usdQuote = await esca.conversions.createQuote({
  sourceCurrency: 'NGN',
  targetCurrency: 'EUR',
  amount: 165_000,
});

const usdConversion = await esca.conversions.convert({
  amount: 165_000,
  sourceCurrency: 'NGN',
  targetCurrency: 'EUR',
  quoteId: usdQuote.quoteId
});

Wallet & Balances

// Get all balances
const balances = await esca.wallet.getBalances();

// Get balance for a specific currency
const usdBalance = await esca.wallet.getBalanceByCurrency('USD');

Files (Documents)

The SDK supports File objects in the browser, and Blob or Uint8Array in Node.js/Bun.

const uint8Array = new Uint8Array([...]);
const response = await esca.files.upload(uint8Array, 'id_card.png');

Webhooks

import { Webhooks } from 'esca-sdk';

// Verify signature in your API route
const isValid = await Webhooks.verifySignature(
  JSON.stringify(request.body),
  request.headers['x-esca-signature'],
  process.env.ESCA_WEBHOOK_SECRET
);

Testing & Mocking

The SDK provides a MockEsca utility and standard fixtures to help you write unit tests without making actual network calls.

import { Esca, MockEsca } from 'esca-sdk';

const esca = new Esca({ apiKey: 'test_key' });
const escaMock = new MockEsca(esca);

// Use pre-built helpers for standard scenarios
escaMock.helpers.mockCreateAccount({ accountName: 'Mocked Account' });

// Or mock any specific method with custom logic
escaMock.mockMethod('wallet', 'getBalances', async () => [
  { currency: 'USD', ledgerBalance: 100, availableBalance: 100 }
]);

// Standard fixtures are also available
const fixture = MockEsca.fixtures.ACCOUNT_FIXTURE;

// Reset mocks after tests
escaMock.resetAll();

Error Handling

The SDK throws descriptive errors to help you handle failures.

import { EscaError, EscaForbiddenError, EscaBatchValidationError } from 'esca-sdk';

try {
  await esca.accounts.create({ ... });
} catch (error) {
  if (error instanceof EscaForbiddenError) {
    // Handle 403 Forbidden (e.g., calling sandbox methods in production)
  } else if (error instanceof EscaBatchValidationError) {
    // Handle bulk operation validation errors
    console.log(error.summary);
    console.log(error.errors);
  } else if (error instanceof EscaError) {
    console.log(error.statusCode);
    console.log(error.code); // Machine-readable error code
  }
}

Sandbox Environment

When using the sandbox environment (environment: 'sandbox'), you can simulate deposits to virtual accounts.

await esca.accounts.simulateDeposit({
  accountId: 123,
  amount: 5000,
  narration: 'Test deposit'
});

Features

• Type-safe: Written in TypeScript with full type definitions for all requests and responses.
• Modern: Uses native fetch (compatible with Node.js 20+, Bun, and Browsers).
• Resilient: Automatic retries with exponential backoff and configurable timeouts.
• Developer Friendly: Pluggable logging with sensitive data masking and powerful mocking utilities.
• Efficient: Supports auto-pagination via async iterators and tree-shaking.
• Cross-platform: Works in Node.js, Bun, and Browser environments.
• Telemetry: Standardized User-Agent and X-SDK-Version headers for improved debugging and monitoring.

Idempotency

For state-changing operations (POST requests), you can pass an idempotencyKey in the options argument to safely retry requests without performing the same operation twice.

await esca.payouts.fiatPayout({
  amount: 1000,
  currency: 'NGN',
  bankCode: '058',
  accountNumber: '0123456789',
  beneficiaryName: 'John Doe'
}, {
  idempotencyKey: 'unique-session-id-123'
});

License

MIT