feat: add weekly financial digest

README.md

@@ -65,7 +65,11 @@ OpenAPI: `backend/app/openapi.yaml`
 - Expenses: CRUD `/expenses`
 - Bills: CRUD `/bills`, pay/mark `/bills/{id}/pay`
 - Reminders: CRUD `/reminders`, trigger `/reminders/run`
-- Insights: `/insights/monthly`, `/insights/budget-suggestion`
+- Insights: `/insights/monthly`, `/insights/budget-suggestion`, `/insights/weekly-summary`
+
+### Weekly Financial Digest
+
+`GET /insights/weekly-summary?week_start=YYYY-MM-DD&currency=INR` returns an authenticated, deterministic weekly digest. The endpoint normalizes `week_start` to the ISO week Monday and includes income, expenses, net flow, daily buckets, category shares and week-over-week deltas, top expenses, upcoming bills due that week, and plain-English trend insights. If `currency` is omitted, the user's preferred currency is used.
 
 ## MVP UI/UX Plan
 - Auth screens: register/login.

app/src/api/insights.ts

@@ -21,6 +21,51 @@ export type BudgetSuggestion = {
   net_flow?: number;
 };
 
+export type WeeklySummary = {
+  week_start: string;
+  week_end: string;
+  currency: string;
+  totals: {
+    income: number;
+    expenses: number;
+    net_flow: number;
+    transaction_count: number;
+    average_daily_expense: number;
+  };
+  previous_week: {
+    expenses: number;
+    change_amount: number;
+    change_pct: number;
+  };
+  categories: Array<{
+    category_id: number | null;
+    category: string;
+    amount: number;
+    share_pct: number;
+    previous_amount: number;
+    change_amount: number;
+    change_pct: number;
+    trend: 'UP' | 'DOWN' | 'FLAT';
+  }>;
+  daily: Array<{ date: string; income: number; expenses: number; net_flow: number }>;
+  top_expenses: Array<{
+    id: number;
+    amount: number;
+    category: string;
+    description: string | null;
+    spent_at: string;
+  }>;
+  upcoming_bills: Array<{
+    id: number;
+    name: string;
+    amount: number;
+    currency: string;
+    due_date: string;
+    autopay_enabled: boolean;
+  }>;
+  insights: string[];
+};
+
 export async function getBudgetSuggestion(params?: {
   month?: string;
   geminiApiKey?: string;
@@ -32,3 +77,14 @@ export async function getBudgetSuggestion(params?: {
   if (params?.persona) headers['X-Insight-Persona'] = params.persona;
   return api<BudgetSuggestion>(`/insights/budget-suggestion${monthQuery}`, { headers });
 }
+
+export async function getWeeklySummary(params?: {
+  weekStart?: string;
+  currency?: string;
+}): Promise<WeeklySummary> {
+  const query = new URLSearchParams();
+  if (params?.weekStart) query.set('week_start', params.weekStart);
+  if (params?.currency) query.set('currency', params.currency);
+  const suffix = query.toString() ? `?${query.toString()}` : '';
+  return api<WeeklySummary>(`/insights/weekly-summary${suffix}`);
+}

packages/backend/app/openapi.yaml

@@ -481,6 +481,66 @@ paths:
             application/json:
               schema: { $ref: '#/components/schemas/Error' }
 
+  /insights/weekly-summary:
+    get:
+      summary: Get weekly financial digest
+      tags: [Insights]
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - in: query
+          name: week_start
+          required: false
+          schema: { type: string, format: date }
+          description: Any date in the requested ISO week. The API normalizes it to Monday.
+        - in: query
+          name: currency
+          required: false
+          schema: { type: string }
+          description: Currency filter. Defaults to the user's preferred currency.
+      responses:
+        '200':
+          description: Weekly digest with totals, trends, categories, daily buckets, top expenses, and due bills.
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+              example:
+                week_start: 2026-03-02
+                week_end: 2026-03-08
+                currency: INR
+                totals:
+                  income: 500
+                  expenses: 200
+                  net_flow: 300
+                  transaction_count: 3
+                  average_daily_expense: 28.57
+                previous_week:
+                  expenses: 100
+                  change_amount: 100
+                  change_pct: 100
+                categories:
+                  - category_id: 1
+                    category: Groceries
+                    amount: 120
+                    share_pct: 60
+                    previous_amount: 100
+                    change_amount: 20
+                    change_pct: 20
+                    trend: UP
+                insights:
+                  - Weekly spending is 100.0% higher than last week.
+        '400':
+          description: Invalid week_start
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Error' }
+        '401':
+          description: Unauthorized
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Error' }
+
 components:
   securitySchemes:
     bearerAuth: