@spreeloop/orange_money 1.0.0

package/src/disbursements/operations/get_transfer_status.ts

@@ -0,0 +1,265 @@
+import Joi from 'joi';
+import { getRequest } from '../../utils/https';
+import { OperationResponse } from '../../utils/operation_response';
+import {
+  DisbursementServiceConfig,
+  DisbursementServiceConfigSchema,
+} from '../implementations/disbursement_service';
+import { DisbursementApiRawStatus, DisbursementStatus } from '../utils/status';
+import { getStatusFromProviderRawStatus } from '../utils/utils';
+export interface GetTransferStatusRequest {
+  token: string;
+  messageId: string;
+}
+
+const GetTransferStatusRequestSchema = Joi.object<GetTransferStatusRequest>({
+  token: Joi.string().required(),
+  messageId: Joi.string().required(),
+}).required();
+
+type GetTransferStatusResponseRawData =
+  | {
+      result: {
+        message: string;
+        data: {
+          createtime: string;
+          subscriberMsisdn: string;
+          amount: number;
+          payToken: string;
+          txnid: string;
+          txnmode: string;
+          txnstatus: string;
+          orderId: string;
+          status: DisbursementApiRawStatus;
+          channelUserMsisdn: string;
+          description: string;
+        };
+      };
+      parameters?: {
+        amount: string;
+        xauth: string;
+        channel_user_msisdn: string;
+        customer_key: string;
+        customer_secret: string | null;
+        final_customer_name: string;
+        final_customer_phone: string;
+      };
+      CreateAt: string;
+      MessageId: string;
+      RefundStep: DisbursementStep;
+    }
+  | {
+      parameters?: {
+        amount: string;
+        xauth: string;
+        channel_user_msisdn: string;
+        customer_key: string;
+        customer_secret: string | null;
+        final_customer_name: string;
+        final_customer_phone: string;
+      };
+      message: string;
+      RefundStep: DisbursementStep;
+    }
+  | {
+      ErrorCode: number;
+      body: string;
+      ErrorMessage: string;
+      parameters?: {
+        amount: string;
+        xauth: string;
+        channel_user_msisdn: string;
+        customer_key: string;
+        customer_secret: string | null;
+        final_customer_name: string;
+        final_customer_phone: string;
+      };
+      CreateAt: string;
+      MessageId: string;
+      RefundStep: DisbursementStep;
+    }
+  | {
+      result: {
+        createtime: string;
+        toChannelMsisdn: string;
+        amount: 498925;
+        payToken: string;
+        txnid: string;
+        txnmode: string;
+        txnmessage: string;
+        txnstatus: string;
+        orderId: string;
+        status: DisbursementApiRawStatus;
+        fromChannelMsisdn: string;
+        description: string;
+      };
+      parameters: {
+        amount: string;
+        xauth: string;
+        channel_user_msisdn: string;
+        customer_key: string;
+        customer_secret: string | null;
+        final_customer_name: string;
+        final_customer_phone: string;
+      };
+      CreateAt: string;
+      RefundStep: DisbursementStep;
+    }
+  | string;
+
+export enum DisbursementStep {
+  TransferSent = '2',
+  InitializingTransfer = '1',
+}
+
+export interface responseData {
+  status?: DisbursementStatus;
+  refundStep?: DisbursementStep;
+}
+
+export type GetTransferStatusResponse = OperationResponse<
+  responseData,
+  GetTransferStatusResponseRawData
+>;
+
+/**
+ * Retrieves the transfer status of a transaction.
+ *
+ * @param {DisbursementServiceConfig} configs - The disbursement service config.
+ * @param {GetTransferStatusRequest} params - The parameters for retrieving the transfer status.
+ * @return {GetTransferStatusResponse} - The method response containing the transfer status.
+ */
+export async function getTransferStatus({
+  configs,
+  params,
+  endPoint,
+}: {
+  configs: DisbursementServiceConfig;
+  params: GetTransferStatusRequest;
+  endPoint: string;
+}): GetTransferStatusResponse {
+  const logger = configs.logger;
+  logger.info(
+    `getTransferStatus is running with params : ${JSON.stringify(params)}`
+  );
+
+  const { error: configsValidationError, value: configsValues } =
+    DisbursementServiceConfigSchema.validate(configs);
+
+  if (configsValidationError) {
+    logger.error(
+      `Invalid DisbursementServiceConfig request parameters. params : ${JSON.stringify(
+        configsValidationError.details
+      )}`
+    );
+    return { error: configsValidationError.details };
+  }
+
+  const { error: paramsValidationError, value: paramsValue } =
+    GetTransferStatusRequestSchema.validate(params);
+
+  if (paramsValidationError) {
+    logger.error(
+      `Invalid getTransferStatus request parameters. params : ${JSON.stringify(
+        paramsValidationError
+      )}`
+    );
+    return { error: paramsValidationError };
+  }
+
+  const headers = {
+    Authorization: `Bearer ${paramsValue.token}`,
+  };
+
+  const body = {
+    customerkey: configsValues.customerKey,
+    customersecret: configsValues.customerSecret,
+  };
+
+  const response = await getRequest<GetTransferStatusResponseRawData>({
+    logger: configsValues.logger,
+    route: endPoint,
+    headers: headers,
+    data: body,
+    rejectUnauthorized: false,
+  });
+
+  if (!response.response) {
+    return { error: response.error };
+  }
+
+  const data = response.response.data;
+
+  if (typeof data === 'string') {
+    // Handle string response.
+    return { error: data };
+  } else if ('result' in data) {
+    // Remove the customer secret from the raw data, because
+    // it is a very sensitive secret.
+    if (data.parameters) {
+      data.parameters.customer_secret = null;
+    }
+    const rawStatus: DisbursementApiRawStatus =
+      'status' in data.result ? data.result.status : data.result.data.status;
+    const status = getStatusFromProviderRawStatus(rawStatus);
+
+    if (data.RefundStep === DisbursementStep.InitializingTransfer) {
+      return {
+        data: {
+          status:
+            status === DisbursementStatus.succeeded
+              ? DisbursementStatus.pending
+              : status,
+          refundStep: data.RefundStep,
+        },
+        raw: data,
+      };
+    }
+
+    return {
+      data: {
+        status: status,
+        refundStep: data.RefundStep,
+      },
+      raw: data,
+    };
+  } else if ('ErrorCode' in data) {
+    if (data.parameters) {
+      data.parameters.customer_secret = null;
+    }
+    if (data.ErrorCode === 5019) {
+      return {
+        data: {
+          status: DisbursementStatus.failed,
+          refundStep: data.RefundStep,
+        },
+        raw: data,
+      };
+    }
+    configsValues.logger.error(
+      `Unexpected ErrorCode : ${JSON.stringify(data)}`
+    );
+
+    return {
+      data: {
+        status: DisbursementStatus.pending,
+        refundStep: data.RefundStep,
+      },
+      raw: data,
+    };
+  } else if (data.RefundStep === DisbursementStep.InitializingTransfer) {
+    if (data.parameters) {
+      data.parameters.customer_secret = null;
+    }
+    return {
+      data: {
+        status: DisbursementStatus.pending,
+        refundStep: data.RefundStep,
+      },
+      raw: data,
+    };
+  }
+
+  // By default, assume we failed to retrieve the disbursement status.
+  return { error: data };
+}

package/src/disbursements/operations/transfer.spec.ts

@@ -0,0 +1,158 @@
+import { AxiosResponse } from 'axios';
+import { Logger } from '../../../../logging/src/logging';
+import * as requests from '../../utils/https';
+import { DisbursementXTargetEnvironmentType } from '../utils/constants';
+import { transfer } from './transfer';
+
+describe('transfer', () => {
+  it('should fail on invalid parameter provided', async () => {
+    const { error, data, raw } = await transfer({
+      configs: {
+        channelUserMsisdn: '',
+        clientId: '',
+        clientSecret: '',
+        customerKey: '',
+        customerSecret: '',
+        pin: '',
+        environment: DisbursementXTargetEnvironmentType.sandbox,
+        logger: new Logger(),
+      },
+      params: {
+        webhook: '',
+        amount: 0,
+        customerPhone: '',
+        customerName: '',
+        token: '',
+      },
+      endPoint: '',
+    });
+
+    expect(data).not.toBeDefined();
+    expect(raw).not.toBeDefined();
+    expect(error).toBeDefined();
+  });
+  it('should fail on invalid phone number provided provided', async () => {
+    const { error, data, raw } = await transfer({
+      configs: {
+        channelUserMsisdn: '237699947943',
+        clientId: 'clientId',
+        clientSecret: 'clientSecret',
+        customerKey: 'customerKey',
+        customerSecret: 'customerSecret',
+        pin: 'pin',
+        environment: DisbursementXTargetEnvironmentType.sandbox,
+        logger: new Logger(),
+      },
+      params: {
+        webhook: 'https://example.com',
+        amount: 100,
+        customerPhone: '69532652',
+        customerName: 'itachi uchiwa',
+        token: 'token',
+      },
+      endPoint: 'https://example.com',
+    });
+
+    expect(data).not.toBeDefined();
+    expect(raw).not.toBeDefined();
+    expect(error).toBeDefined();
+  });
+  it('should fail on request failure', async () => {
+    const postSpy = jest
+      .spyOn(requests, 'postRequest')
+      .mockImplementation()
+      .mockResolvedValue({
+        error: {},
+      });
+    const { error, data, raw } = await transfer({
+      configs: {
+        channelUserMsisdn: '237699947943',
+        clientId: 'clientId',
+        clientSecret: 'clientSecret',
+        customerKey: 'customerKey',
+        customerSecret: 'customerSecret',
+        pin: 'pin',
+        environment: DisbursementXTargetEnvironmentType.sandbox,
+        logger: new Logger(),
+      },
+      params: {
+        webhook: 'https://example.com',
+        amount: 100,
+        customerPhone: '695326522',
+        customerName: 'itachi uchiwa',
+        token: 'token',
+      },
+      endPoint: 'https://example.com',
+    });
+
+    expect(data).not.toBeDefined();
+    expect(raw).not.toBeDefined();
+    expect(postSpy).toHaveBeenCalledTimes(1);
+    expect(error).toBeDefined();
+  });
+  it('should succeed on request succeed', async () => {
+    const postSpy = jest
+      .spyOn(requests, 'postRequest')
+      .mockImplementation()
+      .mockResolvedValue({
+        response: <AxiosResponse>{
+          data: {
+            MD5OfMessageBody: 'MD5OfMessageBody',
+            MD5OfMessageAttributes: 'MD5OfMessageAttributes',
+            MessageId: 'MessageId',
+            ResponseMetadata: {
+              RequestId: 'RequestId',
+              HTTPStatusCode: 200,
+              HTTPHeaders: {
+                'x-amzn-requestid': 'x-amzn-requestid',
+                'x-amzn-trace-id': 'x-amzn-trace-id',
+                'content-type': 'content-type',
+                'content-length': 'content-length',
+              },
+              RetryAttempts: 2,
+            },
+          },
+        },
+      });
+    const { error, data, raw } = await transfer({
+      configs: {
+        channelUserMsisdn: '237699947943',
+        clientId: 'clientId',
+        clientSecret: 'clientSecret',
+        customerKey: 'customerKey',
+        customerSecret: 'customerSecret',
+        pin: 'pin',
+        environment: DisbursementXTargetEnvironmentType.sandbox,
+        logger: new Logger(),
+      },
+      params: {
+        webhook: 'https://example.com',
+        amount: 100,
+        customerPhone: '695326522',
+        customerName: 'itachi uchiwa',
+        token: 'token',
+      },
+      endPoint: 'https://example.com',
+    });
+
+    expect(error).not.toBeDefined();
+    expect(postSpy).toHaveBeenCalledTimes(1);
+    expect(raw).toEqual({
+      MD5OfMessageBody: 'MD5OfMessageBody',
+      MD5OfMessageAttributes: 'MD5OfMessageAttributes',
+      MessageId: 'MessageId',
+      ResponseMetadata: {
+        RequestId: 'RequestId',
+        HTTPStatusCode: 200,
+        HTTPHeaders: {
+          'x-amzn-requestid': 'x-amzn-requestid',
+          'x-amzn-trace-id': 'x-amzn-trace-id',
+          'content-type': 'content-type',
+          'content-length': 'content-length',
+        },
+        RetryAttempts: 2,
+      },
+    });
+    expect(data).toBe('MessageId');
+  });
+});

package/src/disbursements/operations/transfer.ts

@@ -0,0 +1,125 @@
+import Joi from 'joi';
+import { RequestResponse, postRequest } from '../../utils/https';
+import { OperationResponse } from '../../utils/operation_response';
+import {
+  DisbursementServiceConfig,
+  DisbursementServiceConfigSchema,
+} from '../implementations/disbursement_service';
+import { orangeMoneyPhoneNumberWithoutCountryCodeRegex } from '../utils/regex';
+
+export enum TransferMethod {
+  OrangeMoney = 'OrangeMoney',
+}
+
+export interface TransferRequest {
+  webhook: string;
+  amount: number;
+  customerPhone: string;
+  customerName: string;
+  token: string;
+}
+
+export const TransferRequestSchema = Joi.object<TransferRequest>({
+  webhook: Joi.string().uri().required(),
+  amount: Joi.number().integer().min(1).required(),
+  customerPhone: Joi.string()
+    .pattern(orangeMoneyPhoneNumberWithoutCountryCodeRegex)
+    .required(),
+  customerName: Joi.string().required(),
+  token: Joi.string().required(),
+});
+
+export type TransferResponseRawData = {
+  MD5OfMessageBody: string;
+  MD5OfMessageAttributes: string;
+  MessageId: string;
+  ResponseMetadata: {
+    RequestId: string;
+    HTTPStatusCode: number;
+    HTTPHeaders: {
+      'x-amzn-requestid': string;
+      'x-amzn-trace-id': string;
+      date: string;
+      'content-type': string;
+      'content-length': string;
+    };
+    RetryAttempts: number;
+  };
+};
+
+export type TransferResponse = OperationResponse<
+  string,
+  TransferResponseRawData
+>;
+
+/**
+ * Transfers the specified amount of currency to the specified party.
+ *
+ * @param {DisbursementServiceConfig} configs - The disbursement service config.
+ * @param {TransferRequest} params - The transfer parameters.
+ * @return {MethodResponse<string, TransferRawData>} - The method response.
+ */
+export async function transfer({
+  configs,
+  params,
+  endPoint,
+}: {
+  configs: DisbursementServiceConfig;
+  params: TransferRequest;
+  endPoint: string;
+}): TransferResponse {
+  const logger = configs.logger;
+  logger.info(`transfer is running with params : ${JSON.stringify(params)}`);
+
+  const { error: configsValidationError, value: configValues } =
+    DisbursementServiceConfigSchema.validate(configs);
+
+  if (configsValidationError) {
+    logger.error(
+      `Invalid DisbursementServiceConfig request parameters. params : ${JSON.stringify(
+        configsValidationError.details
+      )}`
+    );
+    return { error: configsValidationError.details };
+  }
+
+  const { error: paramsValidationError, value: paramsValues } =
+    TransferRequestSchema.validate(params);
+  if (paramsValidationError) {
+    return {
+      error: `Invalid transfer request parameters. params : ${JSON.stringify(
+        params
+      )}`,
+    };
+  }
+  const header = {
+    Authorization: `Bearer ${paramsValues.token}`,
+  };
+  const body = {
+    customerkey: configValues.customerKey,
+    customersecret: configValues.customerSecret,
+    channelUserMsisdn: configValues.channelUserMsisdn,
+    pin: configValues.pin,
+    webhook: paramsValues.webhook,
+    amount: `${paramsValues.amount}`,
+    final_customer_phone: paramsValues.customerPhone,
+    final_customer_name: paramsValues.customerName,
+    refund_method: TransferMethod.OrangeMoney,
+  };
+
+  const response: RequestResponse<TransferResponseRawData> = await postRequest({
+    logger: logger,
+    route: endPoint,
+    data: body,
+    headers: header,
+  });
+
+  if (!response.response) {
+    return { error: response.error };
+  }
+
+  return {
+    data: response.response.data.MessageId,
+    raw: response.response.data,
+  };
+}

package/src/disbursements/routes/routes.ts

@@ -0,0 +1,54 @@
+import { DisbursementXTargetEnvironmentType } from '../utils/constants';
+
+const apiHost = 'https://omapi.ynote.africa';
+const apiTokenHost = 'https://omapi-token.ynote.africa/oauth2/token';
+
+/**
+ * Orange Money API routes builder.
+ * @class
+ */
+export class Routes {
+  /**
+   * Constructs a new {CommonRoutes}.
+   * @constructor
+   * @param {RoutesParams} config - The required global route configuration.
+   */
+
+  /**
+   * Returns the base route for the API.
+   *  e.g: https://docs.google.com/document/d/1h-gMj7PSGAALxRSofOvLa2g5vF3IpDkUufNrU1hX6Yk/edit?pli=1
+   * @return {string} The base route.
+   */
+  private baseRoute(): string {
+    return `${apiHost}/${DisbursementXTargetEnvironmentType.prod}`;
+  }
+
+  /**
+   * This route is used to create an access token which can then be used to authorize and authenticate towards the other end-points of the API.
+   * e.g : https://docs.google.com/document/d/1h-gMj7PSGAALxRSofOvLa2g5vF3IpDkUufNrU1hX6Yk/edit?pli=1 page 2
+   * @return {string}
+   */
+  createAccessToken(): string {
+    return apiTokenHost;
+  }
+
+  /**
+   * This route is used to transfer an amount from the owner’s account to a payee account (customer).
+   * e.g : https://docs.google.com/document/d/1h-gMj7PSGAALxRSofOvLa2g5vF3IpDkUufNrU1hX6Yk/edit?pli=1 page 4
+   * @return {string} - The transfer route.
+   */
+  transfer(): string {
+    return `${this.baseRoute()}/refund`;
+  }
+
+  /**
+   * This route is used to get the status of a transfer.
+   *
+   * @param {string} Id - The reference of the transfer.
+   * e.g : https://docs.google.com/document/d/1h-gMj7PSGAALxRSofOvLa2g5vF3IpDkUufNrU1hX6Yk/edit?pli=1  page 9
+   * @return {string} - The transfer status route.
+   */
+  transferStatus(Id: string): string {
+    return `${this.baseRoute()}/refund/status/${Id}`;
+  }
+}

package/src/disbursements/utils/constants.ts

@@ -0,0 +1,4 @@
+export enum DisbursementXTargetEnvironmentType {
+  sandbox = 'dev',
+  prod = 'prod',
+}

package/src/disbursements/utils/regex.spec.ts

@@ -0,0 +1,39 @@
+import {
+  merchantPhoneNumberRegex,
+  orangeMoneyPhoneNumberWithoutCountryCodeRegex,
+} from './regex';
+
+describe('Test regex merchant phone number', () => {
+  test('Merchant phone number regex matches valid numbers', () => {
+    const validNumbers = ['699947943', '237699947943'];
+    validNumbers.forEach((number) => {
+      expect(merchantPhoneNumberRegex.test(number)).toBe(true);
+    });
+  });
+
+  test('Merchant phone number regex does not match invalid numbers', () => {
+    const invalidNumbers = ['12345', '23712345', 'abc'];
+    invalidNumbers.forEach((number) => {
+      expect(merchantPhoneNumberRegex.test(number)).toBe(false);
+    });
+  });
+});
+describe('Test regex orange money phone number without country code', () => {
+  test('Oman phone number without country code regex matches valid numbers', () => {
+    const validNumbers = ['696512345', '696898765'];
+    validNumbers.forEach((number) => {
+      expect(orangeMoneyPhoneNumberWithoutCountryCodeRegex.test(number)).toBe(
+        true
+      );
+    });
+  });
+
+  test('Orange money phone number without country code regex does not match invalid numbers', () => {
+    const invalidNumbers = ['12345', '96812345', 'abc'];
+    invalidNumbers.forEach((number) => {
+      expect(orangeMoneyPhoneNumberWithoutCountryCodeRegex.test(number)).toBe(
+        false
+      );
+    });
+  });
+});

package/src/disbursements/utils/regex.ts

@@ -0,0 +1,10 @@
+/**
+ * The merchant number regExp authorized for numbers by y-note.
+ */
+export const merchantPhoneNumberRegex = /^(237)?(69\d{7}$|65[5-9]\d{6}$)/;
+
+/**
+ * The orange money phone number regex for orange money numbers without the country code.
+ */
+export const orangeMoneyPhoneNumberWithoutCountryCodeRegex =
+  /^(69\d{7}$|65[5-9]\d{6}$)/;