@traxionpay/cbsmiddleware 0.0.1

package/src/banking/interfaces/bank-service.interface.ts

@@ -0,0 +1,164 @@
+import { FetchBankBalanceDto } from '../dto/fetch-bank-balance.dto';
+import { AccountTransferDto } from '../dto/account-transfer.dto';
+import { AccountDto, ValidateOtp } from '../dto/account.dto';
+import { TransactionHistoryDto } from '../dto/transaction-history.dto';
+
+/**
+ * Interface defining operations related to bank integration and user account processing.
+ *
+ * Implementing this interface allows support for multiple bank providers (e.g., UBA, Zenith)
+ * and standardizes how balance transactions, OTPs, token management, and transaction history
+ * are handled in the application.
+ *
+ * @export
+ * @interface BankService
+ */
+export interface BankService {
+  /**
+   * Sends a request to a bank's API to process a balance transaction for a specific account.
+   *
+   * @param {FetchBalanceDto} fetchBalanceDto - Data Transfer Object containing account number and bank code.
+   * @returns {Promise<any>} A promise resolving with the bank's response.
+   *
+   * @example
+   * const dto = {
+   *   accountNumber: '1234567890',
+   *   bankCode: '001',
+   *   userId: 42
+   * };
+   * const response = await bankService.processBalanceTransaction(dto);
+   * console.log(response.status); // 'success'
+   */
+  processBalanceTransaction(
+    fetchBalanceDto: FetchBankBalanceDto
+  ): Promise<any>;
+
+  /**
+   * Validates and retrieves user account information using an authorization token.
+   *
+   * @param {string} token - A secure token generated from `generateToken()`.
+   * @param {number} userid - The ID of the user whose account details are being requested.
+   * @returns {*} The user's account data, such as mobile number or account info.
+   *
+   * @example
+   * const accountDetails = bankService.findAccountDetailsRaw('jwt-token-123', 101);
+   * console.log(accountDetails.mobile); // '08012345678'
+   */
+  findAccountDetailsRaw(token: string, userid: number): any;
+
+  /**
+   * Generates and sends a One-Time Password (OTP) to the specified mobile number.
+   *
+   * @param {string} mobile - The user's mobile phone number.
+   * @param {string} acc - The user's bank account number.
+   * @param {string} bankid - The identifier for the target bank.
+   * @returns {string} The generated OTP code.
+   *
+   * @example
+   * const otp = bankService.generateOtp('08012345678', '1234567890', 'UBA');
+   * console.log(otp); // '395281'
+   */
+  generateOtp(mobile: string, acc: string, bankid: string): string;
+
+  /**
+   * Validates an OTP against a reference key or session.
+   *
+   * @param {string} reference - A unique reference associated with the OTP session.
+   * @param {string} otp - The OTP value submitted by the user.
+   * @returns {boolean} Returns true if the OTP is valid; otherwise, false.
+   *
+   * @example
+   * const isValid = bankService.validateOtp('otp-session-id-789', '395281');
+   * console.log(isValid); // true
+   */
+  validateOtp(
+    validateOtp: ValidateOtp
+  ): any;
+
+
+  linkAccount(
+    accountDto: AccountDto
+  )
+
+
+  /**
+   * Generates a random numeric OTP of a given length.
+   *
+   * @param {number} length - Desired length of the OTP (e.g., 4, 6).
+   * @returns {string} A string of random digits.
+   *
+   * @example
+   * const otp = bankService.generateRandomOtp(6);
+   * console.log(otp); // '928173'
+   */
+  generateRandomOtp(length: number): string;
+
+  /**
+   * Generates a token for secure, temporary access or user session tracking.
+   *
+   * @returns {Promise<any>} A promise resolving to the generated token (e.g., JWT).
+   *
+   * @example
+   * const token = await bankService.generateToken();
+   * console.log(token); // 'eyJhbGciOiJI...'
+   */
+  generateToken(): Promise<any>;
+
+  refreshToken(refreshToken: string): Promise<any>;
+
+  /**
+   * Fetches a user's transaction history from a specified date range.
+   *
+   * @param {string} token - A valid authentication token.
+   * @param {number} userid - The ID of the user.
+   * @param {string} dateFrom - Start date in `YYYY-MM-DD` format.
+   * @param {string} dateTo - End date in `YYYY-MM-DD` format.
+   * @returns {*} Transaction data (could be an array or an object, depending on implementation).
+   *
+   * @example
+   * const history = bankService.getTransactionHistory(
+   *   'jwt-token-123',
+   *   101,
+   *   '2024-01-01',
+   *   '2024-01-31'
+   * );
+   * console.log(history.length); // 12 transactions
+   */
+  getTransactionHistory(
+    transactionHistoryDto: TransactionHistoryDto
+  ): any;
+
+  /**
+   * Initiates a fund transfer of a specified amount between two user accounts.
+   *
+   * This method performs the necessary balance validation, debits the sender's account,
+   * credits the recipient's account, and records the transaction securely.
+   *
+   * @param {string} token - A valid authentication token for the user/session.
+   * @param {number} useridFrom - The ID of the user initiating the transfer (sender).
+   * @param {number} useridTo - The ID of the recipient user (receiver).
+   * @param {number} amount - The amount to be transferred.
+   * @returns {*} A result indicating the status of the transfer (e.g., success, error details).
+   *
+   * @example
+   * const result = await bankService.accountTransfer('jwt-token-123', 101, 205, 5000);
+   * console.log(result.status); // 'success'
+   */
+  accountTransfer(
+    token: string,
+    useridFrom: string,
+    useridTo: string,
+    amount: number
+  ): any;
+
+  accountCashIn(
+    accountTransaferDto: AccountTransferDto
+  ): any;
+
+  accountDeposit(
+    accountTransaferDto: AccountTransferDto
+  ): any;
+
+
+
+}