1.3.2 • Published 3d ago

mambu-tool-kit

Licence

ISC

Version

1.3.2

Deps

Size

2.5 MB

Vulns

Weekly

Summary Dependency Versions

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: b.omondi@platcorpgroup.com

Changelog

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

Made with by Platcorp Holdings

Keywords

mambu sdk banking api typescript core-banking financial-services fintech loans deposits clients rest-api openapi platcorp