feat(api): add pagination and metadata to invoice listing

[chibokaxavier]

Fixes #9

📝 Executive Summary

This PR implements Offset-based Pagination for the GET /api/invoices endpoint. By allowing clients to specify page and limit parameters, we significantly reduce payload sizes, improve database performance, and provide a scalable way to handle large datasets.

---

🛠 Key Technical Enhancements

1. Smart Pagination Logic

• Dynamic Querying: Added support for page and limit parameters with automatic defaults (Page 1, Limit 10).

• Input Sanitization: Implemented strict parsing to handle edge cases—negative numbers default to 1, and limits are capped at 100 to prevent "mega-queries."

• Decoupled Architecture: Refactored the app entry point to enable seamless Supertest integration, ensuring high reliability for future API changes.

2. Rich Metadata Response

The response now includes a robust meta object to assist frontend navigation:

total: The absolute count of records in the database.

totalPages: Calculated available pages based on the current limit.

Navigation Helpers: Includes hasNextPage and hasPreviousPage booleans for instant UI state management.

---

⚡ Pagination Response Example

JSON

{
  "data": [ ...invoices ],
  "meta": {
    "total": 450,
    "page": 1,
    "limit": 10,
    "totalPages": 45,
    "hasNextPage": true,
    "hasPreviousPage": false
  },
  "error": null
}

---

📂 Core File Impact

File | Change Type | Description -- | -- | -- invoiceRoutes.js | Update | Integrated query parameter parsing for the GET collection. invoiceService.js | Logic | Implemented slice/offset logic for data retrieval. app.js | Refactor | Enhanced for better test environment compatibility. pagination.test.js | Quality | 14 new tests covering edge cases and bounds.

---

🧪 Testing & Quality Assurance

Verified the implementation with a comprehensive test suite covering malformed inputs and out-of-bounds requests.

Bash

# Test Execution Summary:
Test Suites: 1 passed, 1 total
Tests:       14 passed, 14 total
Snapshots:   0 total
Time:        2.026 s
Coverage:    >95% Statement Coverage

---

🔐 Security & Integrity

• Input Boundary Protection: All query parameters are strictly cast to integers with floor/ceiling boundaries to prevent injection or server strain.

• Error Masking: Service-level failures are caught and returned as sanitized 500 errors in production.

---

✅ Final Checklist

• Performance: Verified that pagination reduces response time for large sets.

• Testing: 14 unit and integration tests passing.

• Documentation: Updated API docs in README.md.

• CI/CD: Branch is green and ready for merge.

[drips-wave]

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

[mikewheeleer]

resolve the conflicts

[chibokaxavier]

@mikewheeleer kindly review all

[mikewheeleer]

Please resolve the conflicts

[mikewheeleer]

@chibokaxavier Resolve the conflicts