Arlo EndUser SDK

A TypeScript SDK for interacting with the Arlo EndUser API platform. This SDK provides a comprehensive interface for managing clients, products, end users, wallets, and transactions, with built-in authentication via @eml-payments/core-sdk.

🚀 Features

• Full TypeScript Support - Complete type definitions for all API entities
• Authentication Integration - Seamless integration with @eml-payments/core-sdk
• Comprehensive API Coverage - All EndUser API endpoints supported
• Error Handling - Built-in retry logic and error management
• Modern Architecture - ESM modules with clean, maintainable code

📦 Installation

npm install @eml-payments/arlo-enduser-sdk

🔧 Prerequisites

This SDK requires the @eml-payments/core-sdk for authentication:

npm install @eml-payments/core-sdk

🏁 Quick Start

import { Client } from '@eml-payments/arlo-enduser-sdk';

// Initialize the client
const client = new Client('https://api.arlo.example.com', {
    timeout: 30000,
    retryAttempts: 3,
    apiKey: 'your-api-key'
});

// Authenticate
await client.login('username', 'password');

// Get about information
const aboutInfo = await client.getAboutInfo();
console.log('API Version:', aboutInfo.version);

// Get clients with pagination
const clients = await client.getClients(1, 10);
console.log(`Found ${clients.totalCount} clients`);

📚 API Reference

Authentication

The SDK integrates with @eml-payments/core-sdk for authentication:

// Login
await client.login('username', 'password');

// Logout
await client.logout();

About Information

const aboutInfo = await client.getAboutInfo();
// Returns: { version: string, environment: string, ... }

Client Management

// Get a specific client
const client = await client.getClient('client-id');

// Get all clients with pagination
const clients = await client.getClients(pageNo, pageSize);

// Get products for a client
const products = await client.getClientProducts('client-id');

Product Management

// Get a specific product
const product = await client.getProduct('product-id');

// Get product by ID (alternative endpoint)
const product = await client.getProductById('product-id');

// Get all products with filtering
const products = await client.getProducts({
    clientId: 'client-id',
    isActive: true,
    pageNo: 1,
    pageSize: 20
});

End User Management

// Create a new end user
const newEndUser = await client.createEndUser({
    email: '[email protected]',
    firstName: 'John',
    lastName: 'Doe',
    clientId: 'client-id'
});

// Get a specific end user
const endUser = await client.getEndUser('enduser-id');

// Get all end users with filtering
const endUsers = await client.getEndUsers({
    clientId: 'client-id',
    pageNo: 1,
    pageSize: 10
});

Wallet Management

// Get a specific wallet
const wallet = await client.getWallet('wallet-id');

// Get wallet accounts for an end user
const accounts = await client.getWalletAccounts({
    endUserId: 'enduser-id',
    pageNo: 1,
    pageSize: 10
});

// Get wallet balances
const balances = await client.getWalletBalances({
    walletId: 'wallet-id',
    clientProductId: 'product-id',
    pageNo: 1,
    pageSize: 10
});

Transaction Management

// Transfer funds between accounts
const transferResult = await client.transferFunds({
    fromAccountId: 'account-1',
    toAccountId: 'account-2',
    amount: 100.00,
    currency: 'USD',
    reference: 'Transfer reference'
});

// Credit an account
const creditTransaction = await client.creditAccount({
    accountId: 'account-id',
    amount: 50.00,
    currency: 'USD',
    reference: 'Credit reference'
});

// Debit an account
const debitTransaction = await client.debitAccount({
    accountId: 'account-id',
    amount: 25.00,
    currency: 'USD',
    reference: 'Debit reference'
});

// Get a specific transaction
const transaction = await client.getTransaction('transaction-id');

// Get account transactions with filtering
const accountTransactions = await client.getAccountTransactions('account-id', {
    pageNo: 1,
    pageSize: 20,
    fromDate: '2024-01-01',
    toDate: '2024-12-31',
    type: 'credit',
    status: 'completed'
});

// Get all transactions with filtering
const transactions = await client.getTransactions({
    walletId: 'wallet-id',
    type: 'debit',
    status: 'pending',
    fromDate: '2024-01-01',
    toDate: '2024-12-31',
    pageNo: 1,
    pageSize: 50
});

🔗 Type Definitions

The SDK includes comprehensive TypeScript definitions for all API entities:

interface Client {
    id: string;
    name: string;
    // ... other properties
}

interface Product {
    id: string;
    name: string;
    isActive: boolean;
    // ... other properties
}

interface ExtendedEndUser {
    id: string;
    email: string;
    firstName: string;
    lastName: string;
    // ... other properties
}

interface Transaction {
    id: string;
    amount: number;
    currency: string;
    type: 'credit' | 'debit';
    status: 'pending' | 'completed' | 'failed';
    // ... other properties
}

interface PaginatedResponse<T> {
    items: T[];
    totalCount: number;
    pageNo: number;
    pageSize: number;
}

⚙️ Configuration Options

When initializing the client, you can pass the following options:

const client = new Client('https://api.arlo.example.com', {
    timeout: 30000,        // Request timeout in milliseconds (default: 30000)
    retryAttempts: 3,      // Number of retry attempts (default: 3)
    apiKey: 'your-api-key' // Optional API key for additional authentication
});

🧪 Error Handling

The SDK includes built-in error handling with automatic retries for transient failures:

try {
    const result = await client.getClients();
} catch (error) {
    console.error('API call failed:', error);
    // Handle error appropriately
}

Errors are automatically retried for:

• Network timeouts
• 5xx server errors
• Rate limiting (429) responses

4xx client errors are not retried as they typically indicate permanent issues.

🧪 Testing

The SDK includes Jest configuration for testing:

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Build the project
npm run build

# Type checking
npm run type-check

Mock Testing

Example test setup with mocking:

import { Client } from '@eml-payments/arlo-enduser-sdk';

// Mock the CoreSDK
jest.mock('@eml-payments/core-sdk', () => ({
  CoreSDK: {
    login: jest.fn().mockResolvedValue({ token: 'mock-token' }),
    logout: jest.fn().mockResolvedValue(undefined),
  },
}));

describe('Client', () => {
    let client: Client;

    beforeEach(() => {
        client = new Client('https://api.test.com');
    });

    it('should authenticate successfully', async () => {
        await client.login('testuser', 'testpass');
        // Assert authentication
    });
});

📁 Project Structure

src/
├── client.ts           # Main Client class
├── index.ts           # Public exports
├── services/
│   └── api.ts         # ApiService with HTTP logic
└── types/
    └── index.ts       # TypeScript definitions

tests/
└── Client.test.ts     # Test suite

examples/
└── basic-usage.ts     # Usage examples

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Make your changes and add tests
4. Ensure tests pass: npm test
5. Ensure code builds: npm run build
6. Commit your changes: git commit -am 'Add some feature'
7. Push to the branch: git push origin feature/your-feature
8. Submit a pull request

📝 Development

Setup

# Clone the repository
git clone https://github.com/EML-Payments/arlo.npm.endusersdk.git
cd arlo.npm.endusersdk

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

Scripts

• npm run build - Build the TypeScript code
• npm run build:watch - Build in watch mode
• npm run test - Run Jest tests
• npm run test:watch - Run tests in watch mode
• npm run type-check - Type check without compilation
• npm run clean - Clean build artifacts

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Related Projects

• @eml-payments/core-sdk - Core authentication SDK
• @eml-payments/arlo-client-sdk - Client-focused SDK

📞 Support

For support and questions:

• Create an issue on GitHub
• Contact the EML Payments development team

Made with ❤️ by EML Payments