Labels: backend feature 200pts
Background:
Most list endpoints use offset-based pagination which is broken for real-time data (items inserted between pages cause duplicates/skips). Cursor-based pagination is stable.
Problem:
GET /api/v1/proposals, GET /api/v1/audit, GET /api/v1/transactions use ?page=N&limit=M pagination. During active event ingestion, page 2 can duplicate items from page 1.
What "Done" Looks Like:
- Replace
page/offset pagination with cursor/limit on all list endpoints
- Cursor = opaque base64-encoded object containing:
{ last_id, last_ledger, direction }
- Response includes
next_cursor and has_more fields
- Backward pagination:
cursor can encode direction: 'prev' for reverse traversal
- Existing
page/offset params still accepted but deprecated (log warning, redirect to cursor)
- Tests: forward pagination, backward pagination, cursor stability during new inserts
Key Files:
backend/src/modules/proposals/proposals.controller.tsbackend/src/modules/audit/audit.controller.tsbackend/src/modules/transactions/transactions.controller.tsbackend/src/shared/ — new pagination.ts cursor utilities
Constraints:
- Cursor is opaque to client (base64, not guessable)
- Invalid cursor returns 400 with helpful error
- Default limit 20, max 100
PR Must Include:
pagination.ts cursor utilities- Cursor pagination on all 3 list endpoints
- Backward pagination
- Deprecation warning for old params
- Tests
Labels:
backendfeature200ptsBackground:
Most list endpoints use
offset-based pagination which is broken for real-time data (items inserted between pages cause duplicates/skips). Cursor-based pagination is stable.Problem:
GET /api/v1/proposals,GET /api/v1/audit,GET /api/v1/transactionsuse?page=N&limit=Mpagination. During active event ingestion, page 2 can duplicate items from page 1.What "Done" Looks Like:
page/offsetpagination withcursor/limiton all list endpoints{ last_id, last_ledger, direction }next_cursorandhas_morefieldscursorcan encodedirection: 'prev'for reverse traversalpage/offsetparams still accepted but deprecated (log warning, redirect to cursor)Key Files:
backend/src/modules/proposals/proposals.controller.tsbackend/src/modules/audit/audit.controller.tsbackend/src/modules/transactions/transactions.controller.tsbackend/src/shared/— newpagination.tscursor utilitiesConstraints:
PR Must Include:
pagination.tscursor utilities