Shared Utils Libary

Installation

To use this shared library, follow the following steps and install it in your project

# install with npm
$ npm install @ngeni-labs/dollar-markets-shared-utils
# install with yarn
$ yarn add @ngeni-labs/dollar-markets-shared-utils

Events

One of the main function of this libary is to manage communication between services. The Events handle the communication between services.

There are two types of events in this libary, for instance events for user model, will be UserCreatedEvent and UserUpdatedEvent. We do use this convention within this libary.

Auth Service (#auth)

MamlakaWrapper

The MamlakaWrapper is typescript wrapper for interacting with Mamlaka's API services. It provides methods to initiate mobile payments, generate card payment links, and withdraw funds to mobile money. This wrapper handles HTTP requests, manages headers, and processes responses from the Mamlaka API.

Usage

import { MamlakaWrapper } from "./mamlaka-wrapper";
import { MamlakaCurrencyEnum } from "./types";

Initialization

Create an instance of the MamlakaWrapper class by providing the base URL, username, and session token:

const mamlaka = new MamlakaWrapper(
  "https://api.mamlaka.com",
  "your-mamlaka-username",
  "your-session-token"
);

###Methods

1. Initiate Mobile Payment

This method initiates a mobile money payment using M-Pesa.

Parameters:

• currency: The currency of the transaction (MamlakaCurrencyEnum).
• payerPhone: The phone number of the payer.
• externalId: An external identifier for the transaction.
• callbackUrl: The URL to be called upon transaction completion.
• amount: The amount to be paid.

Example

const response = await mamlaka.initiateMobilePayment({
  currency: MamlakaCurrencyEnum.USD,
  payerPhone: "1234567890",
  externalId: "txn123",
  callbackUrl: "https://yourcallback.url",
  amount: 100,
});

2. Generate Card Payment Link

This method generates a card payment link.

Parameters:

• impalaMerchantId: The merchant ID.
• currency: The currency of the transaction (MamlakaCurrencyEnum).
• amount: The amount to be paid.
• externalId: An external identifier for the transaction.
• callbackUrl: The URL to be called upon transaction completion.
• redirectUrl: The URL to redirect to after payment.

Example:

const response = await mamlaka.generateCardPaymentLink({
  impalaMerchantId: "your-merchant-id",
  currency: MamlakaCurrencyEnum.USD,
  amount: "100",
  externalId: "txn123",
  callbackUrl: "https://yourcallback.url",
  redirectUrl: "https://yourredirect.url",
});

3. Withdraw to Mobile Money

This method withdraws funds to a mobile money account using M-Pesa.

Parameters:

• currency: The currency of the transaction (MamlakaCurrencyEnum).
• amount: The amount to be withdrawn.
• recipientPhone: The phone number of the recipient.
• externalId: An external identifier for the transaction.
• callbackUrl: The URL to be called upon transaction completion.

Example:

const response = await mamlaka.withdrawToMobileMoney({
  currency: MamlakaCurrencyEnum.USD,
  amount: "100",
  recipientPhone: "0987654321",
  externalId: "txn123",
  callbackUrl: "https://yourcallback.url",
});

Error Handling

Each method catches and logs errors to the console. If an error occurs during the HTTP request, the method returns undefined.