api-gateway settlement listing pagination has no maximum page size

[0xBernny]

Description

This pull request introduces strict defensive safeguards for the settlement listing database queries. It addresses memory-pinning performance risks on the primary database by enforcing max page limits, structured response cursor contracts, and explicit sort schemas.

Key Changes

1. Max Limit Enforcement: Applied a strict capping threshold (MAX_PAGE_SIZE = 100). Request criteria asking for out-of-bounds page sizes are automatically clamped down to ensure predictable database load.
2. Metadata Derivation: Structured the JSON payload layout to supply deep pagination contextual metadata fields (total, limit, nextCursor, hasMore).
3. Sorting Allow-List Protection: Replaced single-column default sorting logic with a validated whitelist lookup matrix (createdAt, amount, status, id), returning an explicit 422 Unprocessable Entity response if an untrusted column vector is injected.

Clamped-Size Structural Response Demonstration

When an agent or client hits the endpoint requesting an unrestricted dataset limit size (e.g., ?limit=50000):

{
  "data": [
    { "id": "set_01", "amount": "250.00", "status": "COMPLETED", "createdAt": "2026-09-03T12:00:00Z" }
    // ... exactly 99 more items truncated safely ...
  ],
  "pagination": {
    "total": 14205,
    "limit": 100,
    "nextCursor": "eyJpZCI6InNldF8xMDAifQ==",
    "hasMore": true
  }
}

Related Issues

• Closes api-gateway settlement listing pagination has no maximum page size #471

Checklist

• I have read the CONTRIBUTING.md guidelines.
• I have updated the documentation accordingly.
• I have added/updated tests for my changes.
• All CI validations pass.

[drips-wave]

@0xBernny 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