[New] Server-Side Pagination Standardization Across All List Endpoints

[Topmatrixmor2014]

Category Labels: backend, pagination, api, performance, refactor

Summary: Standardize cursor-based pagination across every list endpoint in the backend with consistent request/response shapes, documented in docs/api.md.

Background: The backend has backend/src/middleware/pagination.js and backend/src/utils/paginate.js which provide cursor-based pagination. However, not all list endpoints use them consistently. The accounts.js, payments.js, tips.js, events.js, analytics.js, webhooks.js, and turrets.js routes each implement pagination slightly differently. Tests in backend/__tests__/pagination.test.js cover some but not all endpoints.

Problem Statement: Inconsistent pagination across endpoints creates a confusing developer experience. Some endpoints use ?cursor= + ?limit=, others use ?page= + ?size=, and error responses vary.

Objectives:

1. Standardize on cursor-based pagination with parameters: cursor (opaque string), limit (default 20, max 100).
2. Standardize response shape: { data: [...], pagination: { nextCursor, hasMore, total } }.
3. Apply to all list endpoints: accounts, payments, tips, events, analytics, webhooks, turrets, scheduled transactions.
4. Update docs/api.md with the standardized pagination spec.
5. Add pagination tests for all endpoints.

Scope:

• In scope: cursor pagination standardization, response shape, docs, tests.
• Out of scope: offset-based pagination, keyset pagination for different use cases.

Detailed Implementation Requirements:

1. Create backend/src/middleware/pagination.js (unify existing implementations):

   function paginationMiddleware(req, res, next) {
     const cursor = req.query.cursor || null;
     const limit = Math.min(parseInt(req.query.limit) || 20, 100);
     req.pagination = { cursor, limit };
     next();
   }
   module.exports = paginationMiddleware;

2. Create backend/src/utils/paginate.js response formatter:

   function formatPaginatedResponse(data, cursor, total) {
     const hasMore = data.length > 0; // or check against total
     return {
       data,
       pagination: {
         nextCursor: data.length > 0 ? cursor : null,
         hasMore,
         total: total || null,
       }
     };
   }

3. Apply paginationMiddleware to all list routes in backend/src/server.js.
4. Update each route handler:
   • accounts.js: GET /api/v1/accounts/:pk/payments → standardized pagination.
   • payments.js: GET /api/v1/payments/:pk → standardized.
   • tips.js: GET /api/v1/tips/:pk → standardized.
   • events.js: GET /api/v1/events/:pk → standardized.
   • webhooks.js: GET /api/v1/webhooks/:pk → standardized.
   • turrets.js: GET /api/v1/turrets/:pk → standardized.
   • scheduledTransactions.js: GET /api/v1/scheduled/:pk → standardized.
5. Update docs/api.md with a dedicated "Pagination" section.
6. Add/update tests in backend/__tests__/pagination.test.js.

Expected Architecture:

backend/src/
├── middleware/
│   └── pagination.js       (unified)
├── utils/
│   └── paginate.js         (response formatter)
├── routes/                  (updated: standardized pagination)
└── server.js               (apply middleware globally)

docs/api.md                  (pagination section)

Acceptance Criteria:

• All list endpoints accept ?cursor=&limit= parameters.
• All list endpoints return { data, pagination: { nextCursor, hasMore, total } }.
• limit defaults to 20, max 100.
• Documentation in docs/api.md is accurate.
• All existing and new pagination tests pass.
• CI: Backend tests pass in .github/workflows/ci.yml → backend job.

---

---

CI Validation: This issue includes acceptance criteria that must pass CI checks in .github/workflows/ci.yml. PRs solving this issue must pass all relevant CI jobs before merging.

[grantfox-oss]

🦊 GrantFox — @bamiebot-maker has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #344)
2. Your PR will be reviewed by the FinChippay maintainers

Good luck! Track your progress on GrantFox.

[Killerjunior]

I’ve reviewed the issue details and documentation, and I understand the problem statement and expected outcome. Please assign this task to me — I’m ready to start working on it.