Closes #196 Add pagination and stable ordering to expense and settlement lists

[Fury03]

Closes #196

Problem Statement

Settlement records within a group have no dedicated list endpoint with cursor-based pagination. While the ledger endpoint merges expenses, settlements, and treasury transactions, clients that specifically need to list settlements for a group must either use the merged ledger (which interleaves different record types) or the cross-group history endpoint (which scopes to the authenticated user rather than the group).

Solution Comparison and Decision

Option A: Add pagination to a new GET /settlements endpoint — This would list all settlements across all groups, which is not what the issue describes. The issue asks for pagination on "group expenses or settlement records," meaning per-group scoping.

Option B: Rely on the ledger endpoint — The ledger merges expenses, settlements, and treasury transactions. It already has pagination, but a client that only needs settlements must fetch and filter mixed results, wasting bandwidth and making cursor-based pagination impossible across types.

Option C: Add GET /groups/:id/settlements with shared pagination (chosen) — A dedicated endpoint scoped to the group, using the same cursor-based pagination contract as every other list endpoint. This gives clients a stable, deterministic way to page through settlements without mixing types or relying on cross-group history.

The Change

New route in src/routes/settlements.ts:

app.get("/groups/:id/settlements", async (req) => {
  const auth = requireUser(req);
  const { id: groupId } = idParamSchema.parse(req.params);
  const { cursor, limit, order } = paginationQuerySchema.parse(req.query ?? {});
  await requireMembership(groupId, auth.id);

  const position = requireCursor(cursor);
  const settlements = await prisma.settlement.findMany({
    where: { groupId, ...cursorFilter(position, order) },
    include: settlementInclude,
    orderBy: cursorOrderBy(order),
    take: takeForPage(limit),
  });

  const { items, meta } = buildPage(settlements, limit, order);
  return { settlements: items.map(serializeSettlement), meta };
});

Endpoint	Auth	Pagination	Membership
GET /groups/:id/settlements	Required	cursor, limit, order	Checked before any row read

Key behaviors:

• Deterministic (createdAt, id) ordering handles equal timestamps safely
• limit + 1 row fetch computes hasMore without a count query
• Maximum page size enforced server-side
• Cursor carries no membership authority — groupId filter always scopes the query

Compatibility Note

No INTERFACE_VERSION change. This is an additive new endpoint that does not modify existing routes or response shapes. Existing clients are unaffected.

Incidental Fixes

1. Added GET /groups/:id/settlements to the shared pagination contract documentation in docs/api-contract.md.

Testing

New tests (in tests/pagination-contract.test.ts):

• Contract test: returns consistent metadata on an empty page
• Contract test: rejects page size over maximum
• Contract test: rejects malformed cursor
• First page returns items and cursor pointing at last row
• Cursor resume with tie-breaking on id
• Bounded query (limit + 1 rows, no skip)
• Non-member rejection (403 before any row read)
• Cursor scoping: groupId always present, not derived from cursor

Test results: All 757 tests pass (57 test files), including 46 pagination-contract tests.

Additional Notes

Settlement records were previously only accessible through the merged ledger endpoint (GET /groups/:id/ledger) or the cross-group history endpoint (GET /history). This PR adds the dedicated per-group list endpoint that settlement-specific clients need.

[drips-wave]

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

[mergekeeper]

MergeKeeper review unavailable

AI provider review response did not contain valid JSON

No approval or merge action was taken.

[mergekeeper]

MergeKeeper review

Scope: in scope for linked issue #196.
Verdict: clean

Successfully added the paginated GET /groups/:id/settlements endpoint with proper membership checks, cursor handling, documentation, and comprehensive test coverage.

Reviewed commit: 226eec47af0bd0834f499f3e744dcd929bc8bfbf.
CI and merge eligibility are checked separately.

[mergekeeper]

Approved

Successfully added the paginated GET /groups/:id/settlements endpoint with proper membership checks, cursor handling, documentation, and comprehensive test coverage.

[mergekeeper]

MergeKeeper merge status

Status: blocked
PR state: open
Mergeability: mergeable
Checked commit: 226eec47af0bd0834f499f3e744dcd929bc8bfbf.

Reason:
GitHub pull request merge request failed with 405: Base branch was modified. Review and try the merge again.

Next steps:

1. Check the linked GitHub status and repository-rule details.
2. Fix the reported issue or update the repository rule.
3. Push a new commit or retry after the requirement becomes eligible.