feat: smart weekly financial summary digest

[shaidshark]

Summary

Implements a comprehensive weekly financial digest feature as requested in #121.

Features

Weekly Financial Summary

• Overview: Total income, expenses, net flow, and savings rate for the week
• Week-over-Week Trends: Compare spending and income changes from the previous week with percentage changes
• Category Breakdown: Detailed spending analysis by category with amounts, transaction counts, and percentages
• Notable Transactions: Highlights of the largest expenses and income items
• Upcoming Bills: Preview of bills due in the next 7 days with days-until-due countdown
• Smart Insights: AI-generated actionable financial recommendations based on the week's activity

Delivery

• Email Delivery: Professional text-based email format using existing SMTP infrastructure
• Scheduled Generation: Automatic digest generation every Sunday at 9:00 AM UTC via APScheduler
• On-Demand: Users can request their digest anytime via API

New Endpoints

Endpoint	Method	Description
/digest/weekly\	GET	Get weekly digest data (JSON)
/digest/weekly/send\	POST	Send digest email to current user
/digest/weekly/preview\	GET	Preview email subject and body
/scheduler/status\	GET	Check scheduler status

CLI Commands

\\�ash

Generate digest for all users

flask generate-digest

Generate for specific user with email

flask generate-digest --user-id 1 --send-email
\\

Implementation Details

New Files

• \packages/backend/app/services/digest.py\ - WeeklyDigestService class with all digest logic
• \packages/backend/app/services/scheduler.py\ - APScheduler integration for weekly jobs
• \packages/backend/app/routes/digest.py\ - API endpoints for digest
• \packages/backend/tests/test_digest.py\ - Comprehensive test suite

Modified Files

• \packages/backend/app/init.py\ - Scheduler initialization and CLI commands
• \packages/backend/app/routes/init.py\ - Register digest blueprint
• \README.md\ - Documentation for new feature

Testing

Tests cover:

• Week bounds calculation (Monday-Sunday)
• Previous week comparison
• Summary generation with income/expenses
• Category breakdown with percentages
• Notable transactions selection
• Upcoming bills preview
• Insights generation (savings rate, trends, spending alerts)
• Email formatting
• API endpoint authorization and responses

\\�ash

Run digest tests

pytest packages/backend/tests/test_digest.py -v
\\

Example Email

\
Hello user@example.com,

Here's your weekly financial summary for 2024-01-08 to 2024-01-14:

═══════════════════════════════════════════════════
OVERVIEW
═══════════════════════════════════════════════════
Total Income: ,000.00
Total Expenses: .00
Net Flow: .00
Savings Rate: 60.00%
Transactions: 5

═══════════════════════════════════════════════════
INSIGHTS
═══════════════════════════════════════════════════
💡 Excellent savings rate of 60.0%! You're on track for strong financial growth.
💡 Your highest spending category was 'Food' at .00 (75.0% of total).
\\

Acceptance Criteria Met

• Production ready implementation
• Includes tests
• Documentation updated

Fixes #121

[shaidshark]

I pushed a small follow-up to improve merge readiness: removed a redundant imedelta import in the digest route and made the weekly digest email use the user's preferred currency symbol instead of hardcoded USD formatting. This keeps the feature safer for non-USD users without changing the overall digest behavior.