feat: add GET /api/dashboard/stats endpoint

[mrteeednut007-dotcom]

feat: Dashboard Statistics API (GET /api/dashboard/stats)

Summary

Implements the dashboard statistics endpoint that provides authenticated users with aggregated
insights into their contract activity and financial performance.

Changes

• lib/dashboard/stats.ts — Query layer that computes all 4 metrics in a single SQL query using
  COUNT FILTER and SUM FILTER with a LEFT JOIN to escrow_transaction_logs. Scoped to the
  authenticated user as both client and freelancer.
• app/api/dashboard/stats/route.ts — GET /api/dashboard/stats handler protected by JWT auth
  middleware. Returns metrics with Cache-Control: private, max-age=60 for performance.
• app/api/dashboard/stats/stats.test.ts — 8 unit tests covering query logic and all endpoint
  response codes.

Metrics Returned

{
"data": {
"activeContracts": 3,
"completedContracts": 12,
"totalEarnings": "4500.00",
"escrowVolume": "1200.00"
},
"meta": {
"generatedAt": "2026-06-29T06:54:00.000Z"
}
}

┌────────────────────┬──────────────────────────────────────┐
│ Metric │ Source │
├────────────────────┼──────────────────────────────────────────────────────────────────────┤
│ activeContracts │ contracts where status = 'active' │
├────────────────────┼──────────────────────────────────────────────────────────────────────┤
│ completedContracts │ contracts where status = 'completed' │
├────────────────────┼──────────────────────────────────────────────────────────────────────┤
│ totalEarnings │ Sum of confirmed milestone_release transactions in │
│ │ escrow_transaction_logs │
├────────────────────┼──────────────────────────────────────────────────────────────────────┤
│ escrowVolume │ Sum of total_amount on funded/partially_released contracts │
└────────────────────┴──────────────────────────────────────────────────────────────────────┘

Testing

• 8/8 unit tests pass
• Build verified (ƒ /api/dashboard/stats in Next.js output)
• No TypeScript errors introduced

Error Handling

┌──────────────────────────┬────────────────────┐
│ Scenario │ Status │
├──────────────────────────┼────────────────────┤
│ Valid authenticated user │ 200 OK │
├──────────────────────────┼────────────────────────────────────┤
│ Wallet not registered │ 404 USER_NOT_FOUND │
├──────────────────────────┼────────────────────────────────────┤
│ DB/unexpected error │ 500 INTERNAL_ERROR │
├──────────────────────────┼────────────────────────────────────┤
│ Unauthenticated │ 401 AUTH_REQUIRED (via middleware) │
└──────────────────────────┴────────────────────────────────────┘
close #124

[drips-wave]

@mrteeednut007-dotcom 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