fix: phone validation, API parser fuzz tests, and transaction query/index optimizations

[mallison031]

Summary

This pull request addresses and resolves issues #1844, #1845, #1846, and #1853 across the Mobile Money ↔ Stellar bridge service.

1. [Testing] Validate phone number formatting and parsing libraries (#1844)

• Enhanced phoneUtils.ts with comprehensive utilities:
  • parseFlexiblePhoneNumber: parses raw user inputs handling missing '+', leading zeros, double zeros, spaces, dashes, and parentheses.
  • validatePhoneNumber: extracts ParsedPhoneInfo (validity, countryCallingCode, country, e164, international, national, rfc3966 formats).
  • isValidPhoneNumber: boolean check for validity against standard and regional formats.
  • formatPhoneNumber: supports formatting to e164, national, international, and rfc3966.
  • detectProvider: detects mobile network operators (mtn, airtel, orange, vodacom, tigo) from MSISDN prefixes.
  • validatePhoneProviderMatch & formatPhoneForProvider: ensures compliance with provider-specific payload requirements (e.g. Airtel national MSISDN formatting).
• Added exhaustive unit test suites in src/utils/tests/phoneUtils.test.ts covering all providers, country codes (+237, +256, +233, +225, +255), and formatting options.

2. [Testing] Add fuzz testing to API parser inputs (#1845)

• Created dedicated property-based fuzz testing suite in tests/fuzz/apiParsers.fuzz.test.ts using fast-check and boundary attack string pools.
• Fuzz tests all API input parsers:
  • Transaction filter parser (parseStatusFilter, validateTransactionFilters, getPaginationInfo)
  • Date & timestamp parsers (ISO_8601_UTC_REGEX)
  • Phone number parsers and formatters (parseFlexiblePhoneNumber, formatPhoneForProvider, validatePhoneProviderMatch)
  • Stellar G-address validator (isStrictStellarGAddress, assertStrictStellarGAddress)
  • Reference number validator and index checker (isValidReferenceNumber, checkReferenceExists)
• Verified invariant: Parsers never crash the runtime on adversarial, boundary, or malformed inputs and produce well-typed errors.

3. [Refactor] Optimize database query performance on transaction history logs (#1846)

• Enhanced TransactionModel:
  • Added support for userId in TransactionListFilters and buildListWhere to leverage composite index idx_transactions_user_created_id (user_id, created_at DESC, id DESC).
  • Optimized list() and count() query execution plans to leverage existing keyset and composite indexes (status, created_at DESC, id DESC, provider, created_at DESC, id DESC).
• Optimized listTransactionsHandler in transactionController.ts:
  • Removed duplicate sequential queries (findByStatuses + countByStatuses running immediately before list()).
  • Implemented parallel execution using Promise.all and direct filter forwarding.

4. [Refactor] Optimize index checks on transaction reference numbers (#1853)

• Enhanced referenceGenerator.ts:
  • Added checkReferenceExists(referenceNumber) and isReferenceAvailable(referenceNumber) performing index-only EXISTS (SELECT 1 FROM transactions WHERE reference_number = $1) queries against idx_transactions_reference_number.
  • Optimized daily sequence lookup in generateReferenceNumber() to use prefix range conditions (reference_number >= $1 AND reference_number < $2), enabling strict B-tree index scans.
  • Expanded isValidReferenceNumber to support standard system reference formats (TXN-, WTH-, DEP-, REF-).
• Added TransactionModel.checkReferenceExists() and added LIMIT 1 to findByReferenceNumber() for single-row index scan optimization.
• Added comprehensive unit tests in tests/utils/referenceGenerator.test.ts.

---

Issues Closed

• close [Testing] Validate phone number formatting and parsing libraries #1844
• close [Testing] Add fuzz testing to API parser inputs #1845
• close [Refactor] Optimize database query performance on transaction history logs #1846
• close [Refactor] Optimize index checks on transaction reference numbers #1853

[drips-wave]

@mallison031 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits