feat: added settlement reconciliation report

[DTech-Wiz1]

Closes #642

Pull Request: Add Admin Settlement Reconciliation Report Endpoint

Summary

This PR introduces a read-only admin API endpoint for retrieving the latest settlement reconciliation results. The endpoint exposes reconciliation run metadata and a paginated list of unmatched records, enabling operators to investigate settlement discrepancies without relying on logs.

Problem

The settlement reconciler (src/jobs/settlementReconciler.ts) currently compares payout records against the Horizon ledger and detects discrepancies. However, the results are only available through logs, making operational triage difficult during incidents.

Operators need a queryable view of reconciliation results to quickly identify and investigate settlement drift.

Solution

New Admin Endpoint

Added:

GET /api/admin/settlement/reconciliation

Location:

src/routes/admin

Features:

• RBAC-protected admin access
• Read-only operation
• Returns the most recent reconciliation run summary
• Returns unmatched records with cursor pagination
• Uses shared response and pagination patterns

---

Changes

Persistence Layer

Persist reconciliation results from each run, including:

• Matched count
• Unmatched count
• Run timestamp
• Unmatched record details

This allows the latest reconciliation state to be queried without rerunning reconciliation logic.

API Response

Returns:

{
  "success": true,
  "data": {
    "summary": {
      "matchedCount": 1200,
      "unmatchedCount": 12,
      "runTimestamp": "2026-06-30T12:00:00Z"
    },
    "discrepancies": {
      "items": [...],
      "nextCursor": "..."
    }
  }
}

Pagination

Implemented cursor-based pagination using:

src/lib/pagination.ts

to ensure consistency with existing APIs.

Validation

Query parameters are validated using Zod before execution.

Supported parameters include:

• cursor
• limit

Validation failures return standard API error responses.

Metrics

Added a Prometheus gauge via prom-client:

settlement_reconciliation_unmatched_count

The metric reflects the current unmatched record count from the latest reconciliation run.

Type Reuse

The endpoint reuses the reconciler's existing result types and discrepancy definitions rather than recalculating or redefining reconciliation output within the route layer.

---

Guarantees

• No payout records are modified.
• No reconciliation logic is duplicated.
• Endpoint is strictly read-only.
• RBAC enforcement remains required for access.
• Pagination follows the shared cursor contract.

---

Testing

Added/updated tests to verify:

• Authorized admin access
• RBAC rejection for unauthorized users
• Zod query validation
• Cursor pagination behavior
• Response envelope structure
• Correct summary retrieval
• Correct discrepancy retrieval
• Prometheus gauge updates from persisted reconciliation results

---

Operational Impact

Before:

• Reconciliation discrepancies only visible through logs.
• Incident triage required log inspection.

After:

• Latest reconciliation results available via API.
• Discrepancies are queryable and paginated.
• Current unmatched count exposed through Prometheus metrics.
• Settlement drift becomes observable and actionable.

[drips-wave]

@DTech-Wiz1 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