feat(earnings): Freelancer Earnings & Payment Analytics #214

[toppmann]

Overview

Adds a Freelancer Earnings & Payment Analytics dashboard so freelancers can track total earnings, pending escrow, released payments, completed contracts, monthly trends, and paginated transaction history — with date-range filters, currency formatting, and loading / empty / error states.

Related Issue

Closes #214

Changes

Earnings analytics engine

• [ADD] lib/freelancer-earnings.ts
  • Date-range presets (7d, 30d, ytd, all, custom) and filtering helpers.
  • Aggregation for total earnings, pending escrow, released payments, and completed contracts.
  • Monthly series builder (6-month chart axis) and transaction pagination.
  • formatMoney for currency symbols / decimal precision.
  • DB-backed fetch from escrow_transaction_logs + contracts (scoped to authenticated freelancer), with demo fallback when DB is unavailable.
  • Short-lived in-memory cache for repeated metric reads.

API

• [ADD] app/api/freelancer/earnings/route.ts
  • Authenticated GET via withAuth.
  • Resolves wallet → user UUID and returns only that freelancer’s data.
  • Supports preset, from, to, page, pageSize query params.

UI

• [ADD] components/freelancer/earnings-analytics.tsx
  • Responsive summary cards, Recharts monthly bar chart, quick filters, paginated history table.
  • Skeleton loading, friendly empty state (“No transactions yet”), and error / retry messaging.
• [ADD] app/freelancer/earnings/page.tsx — page route at /freelancer/earnings.
• [MODIFY] components/dashboard/sidebar.tsx — Earnings nav item.

Tests

• [ADD] __tests__/freelancer-earnings.test.ts — coverage for formatting, presets, filtering, summary math, empty state, pagination, and demo seed shape.

Verification Results

Local pure-logic check (Node Intl + aggregation helpers):
✅ formatMoney($1,200 / $12.50)
✅ 7d filter kept 2/3 sample txs
✅ summary totalEarnings=1250, pendingEscrow=400

Vitest suite added: __tests__/freelancer-earnings.test.ts
⚠️ Full `pnpm test` not executed in this environment (GitHub REST-only fix; no local clone/install).
Logic covered by unit tests + standalone Node assertion script.

Acceptance Criteria	Status
Responsive charts/cards	✅ Summary cards + Recharts bar chart on /freelancer/earnings
Date-range filtering	✅ Last 7 / 30 days, YTD, All time (+ custom via API)
Proper currency formatting	✅ formatMoney via Intl.NumberFormat
Empty transaction history	✅ “No transactions yet” empty state
Loading states	✅ Skeleton cards + spinner
Error states	✅ Alert + Retry
Auth scoped to freelancer	✅ withAuth + wallet→user UUID ownership filter

[drips-wave]

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