Mambu Tool Kit

A comprehensive TypeScript SDK for Mambu Core Banking API with complete service integration and type safety.

🚀 Features

• Complete TypeScript SDK: Full type safety with auto-generated types from Mambu OpenAPI specifications
• Comprehensive API Coverage: Support for all major Mambu API endpoints including loans, deposits, clients, and more
• Modular Architecture: Each Mambu service is available as a separate module with clean interfaces
• Multiple Build Formats: CommonJS, ES Modules, and UMD builds for maximum compatibility
• Zero Configuration: Simple setup with domain and API key configuration
• Production Ready: Optimized builds, comprehensive error handling, and extensive testing

📦 Installation

Install the package using npm, yarn, or pnpm:

npm install mambu-tool-kit
# or
yarn add mambu-tool-kit
# or
pnpm add mambu-tool-kit

🚀 Quick Start

import { Mambu } from 'mambu-tool-kit';

// Initialize the Mambu client (singleton pattern)
const mambu = Mambu.getInstance();

// Configure with your Mambu domain and API key
mambu.setConfig({
  domain: "https://your-mambu-domain.mambu.com/api",
  apiKey: "YOUR_MAMBU_API_KEY"
});

// Start using the services
const loanProduct = await mambu.loanProducts.getLoanProductById("your-loan-product-id");
console.log(loanProduct);

📚 Usage Guide

Client Initialization

The Mambu client uses a singleton pattern for easy access across your application:

import { Mambu } from 'mambu-tool-kit';

const mambu = Mambu.getInstance();

Configuration

Configure the client with your Mambu instance details:

mambu.setConfig({
  domain: "https://your-mambu-domain.mambu.com/api",
  apiKey: "YOUR_MAMBU_API_KEY"
});

Available Services

All Mambu API services are available as properties on the client instance:

Loan Management

// Loan Products
const loanProduct = await mambu.loanProducts.getLoanProductById("product-id");

// Loan Accounts
const loanAccount = await mambu.loans.getLoanAccountById("account-id");

// Loan Transactions
const feeResponse = await mambu.loanTransactions.makeFee("account-id", {
  predefinedFeeKey: "fee-key",
  installmentNumber: 1,
  notes: "Fee transaction"
});

Deposit Management

// Deposit Accounts
const depositAccounts = await mambu.deposits.getAllDepositAccounts();
const depositAccount = await mambu.deposits.getDepositAccount("client-id", searchCriteria);

// Deposit Transactions (handled by deposits service)
const withdrawal = await mambu.deposits.makeWithdrawal("account-id", {
  amount: 500,
  notes: "Withdrawal transaction"
});

const transfer = await mambu.deposits.makeTransfer("account-id", {
  amount: 1000,
  transferDetails: {
    linkedAccountKey: "target-account-key"
  }
});

Client Management

// Clients
const client = await mambu.clients.getClientById("client-id");

// Client Documents
const documents = await mambu.clientDocuments.getDocumentsForClient("client-id");

Configuration & Administration

// Branches
const branches = await mambu.branches.getAllBranches();

// Custom Fields
const customFields = await mambu.customFields.getCustomFieldsForEntity("CLIENT");

// Users
const users = await mambu.users.getAllUsers();

Type Safety

Import and use TypeScript types for full type safety:

import { Mambu } from 'mambu-tool-kit';
import type { LoanProduct, DepositAccount, Client } from 'mambu-tool-kit';

const mambu = Mambu.getInstance();

// Fully typed responses
const loanProduct: LoanProduct = await mambu.loanProducts.getLoanProductById("id");
const client: Client = await mambu.clients.getClientById("client-id");

🔧 API Reference

Core Services

| Service | Description | Key Methods | |---------|-------------|-------------| | loanProducts | Loan product management | getLoanProductById, updateLoanProduct | | loans | Loan account operations | See Detailed Loans API Reference below | | loanTransactions | Loan transaction processing | makeFee, makeRepayment, makeDisbursement, makeCredit, makeDebit | | deposits | Deposit account & transaction operations | getAllDepositAccounts, createDepositAccount, makeWithdrawal, makeDeposit | | clients | Client management | getClientById, createClient, updateClient | | branches | Branch management | getAllBranches, getBranchById | | customFields | Custom field management | getCustomFieldsForEntity | | users | User management | getAllUsers, getUserById | | clientDocuments | Client document management | getDocumentsByClientId, createDocument | | documents | General document management | createDocument, downloadDocumentById, deleteDocument |

Loans Service API Reference

The loans service provides comprehensive loan account management capabilities. Below is the complete list of available methods:

Account Management

| Method | Parameters | Return Type | Description | |--------|------------|-------------|-------------| | getById | loanId: string | Promise<LoanAccount> | Retrieves a loan account by its ID | | getAllLoanAccounts | query?: QueryParams | Promise<{data: LoanAccount[], pagination: PaginationInfo}> | Retrieves all loan accounts with pagination metadata | | create | loanAccount: LoanAccount | Promise<LoanAccount> | Creates a new loan account | | update | loanAccountId: string, loanAccount: LoanAccount | Promise<LoanAccount> | Updates a loan account's information | | delete | loanAccountId: string | Promise<void> | Deletes a loan account | | patch | loanAccountId: string, patchOperations: PatchOperation[] | Promise<void> | Partially updates a loan account using JSON Patch operations | | search | searchCriteria: LoanAccountSearchCriteria | Promise<LoanAccount[]> | Searches for loan accounts based on specified criteria | | getPaginatedLoans | searchCriteria?: LoanAccountSearchCriteriaWithPagination | AsyncGenerator<LoanAccount[]> | Retrieves all loan accounts in a paginated manner using an async generator |

Schedule Management

| Method | Parameters | Return Type | Description | |--------|------------|-------------|-------------| | getLoanAccountSchedule | loanAccountId: string | Promise<LoanAccountSchedule> | Retrieves the loan schedule for a loan account | | updateLoanAccountSchedule | loanAccountId: string, installments: Installment[] | Promise<LoanAccountSchedule> | Updates a loan account schedule | | previewProcessPMTTransactionally | loanAccountId: string | Promise<LoanAccountPreviewProcessPMTTransactionally> | Previews a loan account schedule using transactional processing for PMT | | previewTranchesOnSchedule | loanAccountId: string, tranches: LoanTranche[] | Promise<LoanAccountSchedule> | Previews a loan account schedule with tranches | | previewSchedule | schedule: PreviewLoanAccountSchedule | Promise<LoanAccountSchedule> | Previews a loan account schedule for non-existent loan account |

Tranche Management

| Method | Parameters | Return Type | Description | |--------|------------|-------------|-------------| | getLoanAccountTranches | loanAccountId: string | Promise<LoanTranche[]> | Retrieves the loan account tranches list | | updateLoanAccountTranches | loanAccountId: string, tranches: LoanTranche[] | Promise<LoanTranche[]> | Updates the loan account tranches list |

Transaction Management

| Method | Parameters | Return Type | Description | |--------|------------|-------------|-------------| | getLoanTransactionById | loanTransactionId: string, detailsLevel?: 'BASIC' \| 'FULL' | Promise<LoanTransaction> | Retrieves a loan transaction by its ID | | searchLoanTransactions | searchCriteria: LoanTransactionSearchCriteria, offset?: number, limit?: number, paginationDetails?: 'ON' \| 'OFF', cursor?: string, detailsLevel?: 'BASIC' \| 'FULL' | Promise<LoanTransaction[]> | Searches loan transactions by various criteria | | getTransactionsForAllLoanAccountVersions | loanAccountId: string, offset?: number, limit?: number, paginationDetails?: 'ON' \| 'OFF', detailsLevel?: 'BASIC' \| 'FULL' | Promise<LoanTransaction[]> | Retrieves loan transactions for all loan account versions | | adjustLoanTransaction | loanTransactionId: string, details: LoanTransactionAdjustmentDetails | Promise<LoanTransaction> | Adjusts a loan transaction |

Payment Operations

| Method | Parameters | Return Type | Description | |--------|------------|-------------|-------------| | makePrincipalOverpayment | loanAccountId: string, input: PrincipalOverpaymentLoanTransactionInput | Promise<LoanTransaction> | Makes a non-scheduled principal overpayment transaction | | makeRepayment | loanAccountId: string, input: RepaymentLoanTransactionInput | Promise<LoanTransaction> | Makes a repayment transaction on a loan account | | makeDisbursement | loanAccountId: string, input: DisbursementLoanTransactionInput | Promise<LoanTransaction> | Makes a disbursement on a loan | | makeWithdrawalRedraw | loanAccountId: string, input: WithdrawalRedrawTransactionInput | Promise<LoanTransaction> | Makes a withdrawal from redraw balance | | applyPaymentMade | loanAccountId: string, input: PaymentMadeTransactionInput | Promise<LoanTransaction> | Makes a payment in redraw balance for a loan account |

Account Actions

| Method | Parameters | Return Type | Description | |--------|------------|-------------|-------------| | lockLoanAccount | loanAccountId: string, input: LockLoanAccountInput | Promise<LockLoanTransactionsWrapper> | Locks loan account income sources (interest, fees, penalties) | | unlockLoanAccount | loanAccountId: string, input: UnlockLoanAccountInput | Promise<LockLoanTransactionsWrapper> | Unlocks loan account income sources (interest, fees, penalties) | | undoWriteOff | loanAccountId: string, details: LoanActionDetails | Promise<void> | Undoes a write-off for a loan account | | payOffLoanAccount | loanAccountId: string, input: LoanAccountPayOffInput | Promise<void> | Pays off a loan account | | changePeriodicPayment | loanAccountId: string, input: ChangePeriodicPaymentLoanAccountInput | Promise<void> | Changes the periodic payment amount for an active loan | | refinanceLoanAccount | loanAccountId: string, input: RefinanceLoanAccountAction | Promise<LoanAccount> | Refinances a loan account | | rescheduleLoanAccount | loanAccountId: string, input: RescheduleLoanAccountAction | Promise<LoanAccount> | Reschedules a loan account |

Balance & Interest Management

| Method | Parameters | Return Type | Description | |--------|------------|-------------|-------------| | getLoanAccountBalances | loanAccountId: string | Promise<LoanAccountBalances> | Retrieves loan account balances | | applyBalanceInterest | loanAccountId: string, loanAccountBalance: string, input: ApplyBalanceInterestInput | Promise<LoanAccountBalanceChanges> | Applies interest on a loan account balance | | previewPayOffAmounts | loanAccountId: string, input: PreviewPayOffDueAmountsInAFutureDateInput | Promise<PreviewPayOffDueAmountsInAFutureDateWrapper> | Previews pay off due amounts in a future date |

Product & Funding Management

| Method | Parameters | Return Type | Description | |--------|------------|-------------|-------------| | getLoanProduct | productType: string | Promise<LoanProduct> | Retrieves a loan product based on the provided product type | | createLoanAccountFundingSources | loanAccountId: string, funds: InvestorFund[] | Promise<InvestorFund[]> | Creates funding sources for a loan account | | updateLoanAccountFundingSources | loanAccountId: string, funds: InvestorFund[] | Promise<InvestorFund[]> | Updates loan account funding sources | | deleteLoanAccountFundingSources | loanAccountId: string | Promise<void> | Deletes loan account funding sources |

Card Management

| Method | Parameters | Return Type | Description | |--------|------------|-------------|-------------| | deleteCard | loanAccountId: string, cardReferenceToken: string | Promise<void> | Deletes a card associated with an account using its reference token |

Usage Examples

// Basic loan account retrieval
const loan = await mambu.loans.getById("loan-123");

// Paginated loan retrieval with async generator
for await (const loanBatch of mambu.loans.getPaginatedLoans({
  limit: 50,
  accountState: 'ACTIVE',
  detailsLevel: 'FULL'
})) {
  loanBatch.forEach(loan => console.log(loan.id));
}

// Search with criteria
const activeLoans = await mambu.loans.search({
  filterCriteria: [{
    field: 'accountState',
    operator: 'EQUALS',
    value: 'ACTIVE'
  }]
});

// Make a repayment
const repayment = await mambu.loans.makeRepayment("loan-123", {
  amount: 1000,
  notes: "Monthly payment"
});

Configuration Methods

| Method | Description | |--------|-------------| | setConfig(config) | Configure domain and API key | | getInstance() | Get singleton instance |

🛠️ Development

Requirements

• Node.js 16+
• npm 8+
• TypeScript 5.6+

Building from Source

# Clone the repository
git clone https://git.platcorpgroup.com/platcorp/mambu-tool-kit.git
cd mambu-tool-kit

# Install dependencies
npm install

# Generate types and build
npm run build

# Run tests
npm test

📄 License

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

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

📞 Support

• Issues: GitHub Issues
• Documentation: API Reference
• Email: [email protected]

🔗 Related Projects

• Mambu API Documentation
• Mambu Developer Portal

📈 Changelog

See CHANGELOG.md for a detailed history of changes to this project.

Made with ❤️ by Platcorp Holdings