feat: invoice state machine, Soroban utilities, and invoice endpoints

[EmmanuelOchaje]

Summary

This PR implements all four issues related to invoice management utilities and API endpoints:

• [BACKEND] Add unit tests for invoice status state machine valid and invalid transitions #164: Add unit tests for invoice status state machine valid and invalid transitions
• [BACKEND] Add helper for validating Soroban contract ID C-address format #163: Add helper for validating Soroban contract ID C-address format
• [BACKEND] Add endpoint GET /api/v1/invoices/:id/tokens for querying invoice token holders #161: Add endpoint GET /api/v1/invoices/:id/tokens for querying invoice token holders
• [BACKEND] Add endpoint GET /api/v1/invoices/:id/escrow for querying on-chain escrow state #160: Add endpoint GET /api/v1/invoices/:id/escrow for querying on-chain escrow state

Implementation Details

Issue #164 - Invoice State Machine

• File: src/utils/invoice-state.utils.ts

  • New function: isValidInvoiceStateTransition(currentStatus, targetStatus): boolean
  • Validates the invoice lifecycle state machine with allowed transitions:
    • DRAFT → PUBLISHED, CANCELLED
    • PENDING → PUBLISHED, CANCELLED
    • PUBLISHED → FUNDED, CANCELLED
    • FUNDED → SETTLED, CANCELLED
    • SETTLED → CANCELLED
    • CANCELLED → (no transitions)

• File: tests/unit/utils/invoice-state-machine.test.ts

  • Comprehensive test coverage for all 36 state transition permutations
  • Tests valid transitions, invalid transitions, self-transitions, and backward transitions

Issue #163 - Soroban Contract ID Validator

• File: src/utils/stellar-address.utils.ts

  • New function: isValidSorobanContractId(contractId: string): boolean
  • Uses StrKey.isValidContract() from stellar-sdk to validate 56-character C-address format

• File: tests/unit/utils/stellar-address.test.ts

  • Tests for valid and invalid Soroban contract IDs
  • Ensures contract IDs are distinguished from Stellar public keys

Issue #161 - Invoice Token Holders Endpoint

• File: src/controllers/invoice.controller.ts

  • New handler: getInvoiceTokenHolders()

• File: src/services/invoice.service.ts

  • New method: getInvoiceTokenHolders(invoiceId: string)
  • Queries investments table grouped by investor wallet address
  • Calculates token balance and percentage share for each holder
  • Returns array with wallet address, investment amount, percentage share, and status

• File: src/routes/invoice.routes.ts

  • New route: GET /api/v1/invoices/:id/tokens
  • Requires JWT authentication

Issue #160 - Invoice Escrow Status Endpoint

• File: src/controllers/invoice.controller.ts

  • New handler: getInvoiceEscrowStatus()

• File: src/services/invoice.service.ts

  • New method: getInvoiceEscrowStatus(invoiceId: string)
  • Returns on-chain escrow contract information

• File: src/routes/invoice.routes.ts

  • New route: GET /api/v1/invoices/:id/escrow
  • Requires JWT authentication

Test Coverage

• 30+ unit tests for invoice state machine transitions
• 10+ unit tests for Soroban contract ID validation
• Full coverage of valid/invalid state transitions
• Tests for edge cases and error scenarios

Closes #164, Closes #163, Closes #161, Closes #160.

[drips-wave]

@EmmanuelOchaje 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