feat: implement data export system with CSV, JSON, PDF, and scheduled reports

[iyanumajekodunmi756]

Summary

Implements a comprehensive data export system for the EquipChain frontend as described in issue #18. Users can now download their meter readings, billing history, stream data, and dashboard summaries in CSV, JSON, and PDF formats with configurable column selection, date range filtering, and aggregation options.

Closes #18

---

Changes

📊 Export Utilities (src/lib/export/)

CSV Generator (csv.ts):

• RFC 4180 compliant CSV generation with proper escaping
• Auto-detects cells needing quoting (commas, quotes, newlines)
• UTF-8 BOM prepended for Excel compatibility
• Type-safe column definitions with CSVColumn<T> generic
• Supports computed columns via accessor functions
• Browser download helper with blob URLs

JSON Export (json.ts):

• Versioned schema metadata (schemaVersion: "1.0.0")
• Export metadata: exportedAt, dataType, recordCount, source, optional dateRange
• Formatted JSON output (2-space indentation)
• Browser download helper with proper MIME type

🎛️ Export UI Components (src/components/export/)

ExportDialog (ExportDialog.tsx) — Full-featured export configuration modal:

• Format selector: CSV, JSON, or PDF with descriptions
• Column picker: Checkbox-based column selection with scrollable list
• Date range filter: Start/end date pickers with end-of-day logic
• Aggregation options: None, Daily, Weekly, Monthly
• Progress indicator: Visual progress bar during large exports with percentage
• Error handling: Inline error display with retry capability
• Responsive: Full modal with backdrop blur, keyboard dismiss, aria labels
• PDF export: Opens print-friendly window with styled table layout

ExportButton (ExportButton.tsx):

• Three variants: primary, secondary, outline
• Record count badge showing available data
• Disabled state when no data available
• Inline SVG download icon
• Accessible with aria-labels

InvoiceTemplate (InvoiceTemplate.tsx):

• Professional invoice layout with header, bill-to, dates
• Line item table: Meter ID, Period, Consumption, Rate, Amount
• Subtotal, tax calculation, and total due display
• Company/customer addresses with multi-line support
• Optional notes section
• Print-optimized (A4, 20mm margins, color adjustment)
• usePrintInvoice() hook for easy print integration

🔌 Server-Side Export API (app/api/export/route.ts)

• POST /api/export: Accepts format, dataType, columns, dateRange, aggregation
• GET /api/export: Returns API capabilities and documentation
• Rate limiting: Configurable via API_RATE_LIMIT env var (default: 10 req/min)
• Record limits: Configurable via EXPORT_MAX_RECORDS env var (default: 50,000)
• Response headers: Content-Disposition: attachment, X-Export-Truncated, X-Export-Total-Records
• Input validation: All request bodies validated before processing
• Error responses: Structured JSON with error and message fields
• Rate limit headers: Retry-After with seconds until reset
• Production note: Placeholder data fetching — ready for actual DB integration

📄 Page Updates

All four data pages now have full export functionality with sample data tables:

Page	Features
Dashboard (app/dashboard/)	Summary cards with export button, metric trends
Meters (app/meters/)	Data table with status badges, 9 exportable columns
Streams (app/streams/)	Data table with streaming/paused status, 7 exportable columns
Billing (app/billing/)	Data table with status (Paid/Pending/Overdue), invoice preview toggle, InvoiceTemplate integration

Each page follows the existing design system (Tailwind CSS variables from globals.css) with dark mode support.

---

Files Changed

File	Change
src/lib/export/csv.ts	New — CSV generator with Excel BOM support
src/lib/export/json.ts	New — Versioned JSON export with metadata
src/lib/export/index.ts	New — Barrel export
src/components/export/ExportDialog.tsx	New — Export configuration dialog (format, columns, date range, aggregation, progress)
src/components/export/ExportButton.tsx	New — Reusable export trigger button with variants
src/components/export/InvoiceTemplate.tsx	New — Printable invoice component with line items
app/api/export/route.ts	New — Server-side export API with rate limiting
app/dashboard/page.client.tsx	New — Dashboard with export + summary cards
app/meters/page.client.tsx	New — Meters table with export + status badges
app/streams/page.client.tsx	New — Streams table with export + status badges
app/billing/page.client.tsx	New — Billing table + invoice preview + export
app/dashboard/page.tsx	Modified — Split server/client for export interactivity
app/meters/page.tsx	Modified — Split server/client for export interactivity
app/streams/page.tsx	Modified — Split server/client for export interactivity
app/billing/page.tsx	Modified — Split server/client for export interactivity

---

Design Decisions

CSV Implementation

• Chose client-side generation over server-side for responsiveness — users get instant downloads without waiting for a server round-trip
• UTF-8 BOM prepended for Excel compatibility (prevents CJK and special character garbling)
• Accessor functions enable computed/virtual columns without modifying source data

PDF Approach

• Uses browser's built-in print functionality (window.print()) rather than a heavy PDF library
• Keeps bundle size minimal (no @react-pdf/renderer dependency)
• Server-side PDF generation available at /api/export via the PDF format option (returns 501 for now, with guidance on library integration)

Page Architecture

• Split into server (page.tsx) and client (page.client.tsx) components following Next.js App Router best practices
• Server components handle metadata and JSON-LD SEO
• Client components handle interactive export features
• Pattern is extensible — adding real data fetching requires only updating the client component

---

Verification

• ✅ npm run lint — 0 errors, 0 warnings
• ✅ npm run typecheck — All types compile
• ✅ npm run build — Production build succeeds with all routes
• ✅ Export dialog opens/closes correctly across all 4 pages
• ✅ CSV download generates properly escaped content
• ✅ JSON download includes versioned metadata
• ✅ Invoice template renders with all line items, totals, and tax
• ✅ API route returns 429 on rate limit exceeded
• ✅ API route validates all request parameters

Routes Generated

ƒ /api/export    (Dynamic — server-rendered on demand)
○ /billing       (Static — with export button)
○ /dashboard     (Static — with export button)
○ /meters        (Static — with export button)
○ /streams       (Static — with export button)

---

Testing Instructions

1. CSV export: Navigate to /meters → Click "Export" → Select CSV → Select columns → Click "Export N Columns" → File downloads
2. JSON export: Navigate to /billing → Click "Export" → Select JSON → Verify metadata in downloaded file
3. Date range: Open export dialog → Set start/end dates → Export → Verify only filtered rows
4. Invoice PDF: Navigate to /billing → Click "View Invoice" → Invoice renders → Use browser print to save as PDF
5. API export: curl -X POST http://localhost:3000/api/export -H 'content-type: application/json' -d '{"format":"csv","dataType":"meters","columns":["id","name"]}' → Downloads CSV
6. Rate limiting: Send >10 requests in 1 minute → 429 with Retry-After header