{/* ── Summary cards (backend already excludes skipped from totals) ── */}
-
+
diff --git a/img/Selection_1490.png b/img/Selection_1490.png
new file mode 100644
index 0000000..461e015
Binary files /dev/null and b/img/Selection_1490.png differ
diff --git a/package-lock.json b/package-lock.json
index 749c876..0c899c1 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "bill-tracker",
- "version": "0.17",
+ "version": "0.18.1",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "bill-tracker",
- "version": "0.17",
+ "version": "0.18.1",
"dependencies": {
"@radix-ui/react-alert-dialog": "^1.1.2",
"@radix-ui/react-checkbox": "^1.1.2",
diff --git a/package.json b/package.json
index 2b85164..6f5e40e 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "bill-tracker",
- "version": "0.18",
+ "version": "0.18.1",
"description": "Monthly bill tracking system",
"main": "server.js",
"scripts": {
diff --git a/routes/analytics.js b/routes/analytics.js
new file mode 100644
index 0000000..ff918b9
--- /dev/null
+++ b/routes/analytics.js
@@ -0,0 +1,276 @@
+const express = require('express');
+const router = express.Router();
+const { getDb } = require('../db/database');
+
+function parseInteger(value, fallback) {
+ if (value === undefined || value === null || value === '') return fallback;
+ const parsed = Number(value);
+ return Number.isInteger(parsed) ? parsed : NaN;
+}
+
+function monthKey(year, month) {
+ return `${year}-${String(month).padStart(2, '0')}`;
+}
+
+function monthLabel(year, month) {
+ return new Date(Date.UTC(year, month - 1, 1)).toLocaleString('en-US', {
+ month: 'short',
+ year: '2-digit',
+ timeZone: 'UTC',
+ });
+}
+
+function addMonths(year, month, delta) {
+ const date = new Date(Date.UTC(year, month - 1 + delta, 1));
+ return { year: date.getUTCFullYear(), month: date.getUTCMonth() + 1 };
+}
+
+function monthEndDate(year, month) {
+ const day = new Date(Date.UTC(year, month, 0)).getUTCDate();
+ return `${monthKey(year, month)}-${String(day).padStart(2, '0')}`;
+}
+
+function buildMonths(endYear, endMonth, count) {
+ return Array.from({ length: count }, (_, index) => {
+ const value = addMonths(endYear, endMonth, index - count + 1);
+ return {
+ ...value,
+ key: monthKey(value.year, value.month),
+ label: monthLabel(value.year, value.month),
+ start: `${monthKey(value.year, value.month)}-01`,
+ end: monthEndDate(value.year, value.month),
+ };
+ });
+}
+
+function validateSummaryQuery(query) {
+ const now = new Date();
+ const year = parseInteger(query.year, now.getFullYear());
+ const month = parseInteger(query.month, now.getMonth() + 1);
+ const months = parseInteger(query.months, 12);
+ const categoryId = parseInteger(query.category_id, null);
+ const billId = parseInteger(query.bill_id, null);
+ const includeInactive = query.include_inactive === 'true';
+ const includeSkipped = query.include_skipped !== 'false';
+
+ if (!Number.isInteger(year) || year < 2000 || year > 2100) {
+ return { error: 'year must be a 4-digit integer between 2000 and 2100' };
+ }
+ if (!Number.isInteger(month) || month < 1 || month > 12) {
+ return { error: 'month must be an integer between 1 and 12' };
+ }
+ if (!Number.isInteger(months) || months < 1 || months > 36) {
+ return { error: 'months must be an integer between 1 and 36' };
+ }
+ if (categoryId !== null && (!Number.isInteger(categoryId) || categoryId < 1)) {
+ return { error: 'category_id must be a positive integer' };
+ }
+ if (billId !== null && (!Number.isInteger(billId) || billId < 1)) {
+ return { error: 'bill_id must be a positive integer' };
+ }
+
+ return { year, month, months, categoryId, billId, includeInactive, includeSkipped };
+}
+
+function isMonthInPast(year, month) {
+ const now = new Date();
+ const currentMonthStart = new Date(now.getFullYear(), now.getMonth(), 1);
+ const targetMonthStart = new Date(year, month - 1, 1);
+ return targetMonthStart < currentMonthStart;
+}
+
+function buildBillWhere({ userId, categoryId, billId, includeInactive }) {
+ const clauses = ['b.user_id = ?'];
+ const params = [userId];
+ if (!includeInactive) clauses.push('b.active = 1');
+ if (categoryId) {
+ clauses.push('b.category_id = ?');
+ params.push(categoryId);
+ }
+ if (billId) {
+ clauses.push('b.id = ?');
+ params.push(billId);
+ }
+ return { where: clauses.join(' AND '), params };
+}
+
+router.get('/summary', (req, res) => {
+ const parsed = validateSummaryQuery(req.query);
+ if (parsed.error) return res.status(400).json({ error: parsed.error });
+
+ const db = getDb();
+ const userId = req.user.id;
+ const rangeMonths = buildMonths(parsed.year, parsed.month, parsed.months);
+ const startDate = rangeMonths[0].start;
+ const endDate = rangeMonths[rangeMonths.length - 1].end;
+ const billWhere = buildBillWhere({ ...parsed, userId });
+
+ const categories = db.prepare(`
+ SELECT id, name
+ FROM categories
+ WHERE user_id = ?
+ ORDER BY name COLLATE NOCASE
+ `).all(userId);
+
+ const bills = db.prepare(`
+ SELECT b.id, b.name, b.category_id, b.expected_amount, b.active, b.created_at,
+ c.name AS category_name
+ FROM bills b
+ LEFT JOIN categories c ON c.id = b.category_id AND c.user_id = b.user_id
+ WHERE ${billWhere.where}
+ ORDER BY b.name COLLATE NOCASE
+ `).all(...billWhere.params);
+
+ if (!bills.length) {
+ return res.json({
+ range: { year: parsed.year, month: parsed.month, months: parsed.months, start: startDate, end: endDate },
+ filters: {
+ category_id: parsed.categoryId,
+ bill_id: parsed.billId,
+ include_inactive: parsed.includeInactive,
+ include_skipped: parsed.includeSkipped,
+ },
+ categories,
+ bills: [],
+ monthly_spending: [],
+ expected_vs_actual: [],
+ category_spend: [],
+ heatmap: { months: rangeMonths.map(({ key, label, year, month }) => ({ key, label, year, month })), rows: [] },
+ generated_at: new Date().toISOString(),
+ });
+ }
+
+ const billIds = bills.map(b => b.id);
+ const placeholders = billIds.map(() => '?').join(',');
+
+ const paymentRows = db.prepare(`
+ SELECT p.bill_id,
+ substr(p.paid_date, 1, 7) AS month_key,
+ SUM(p.amount) AS total
+ FROM payments p
+ JOIN bills b ON b.id = p.bill_id
+ WHERE b.user_id = ?
+ AND p.bill_id IN (${placeholders})
+ AND p.paid_date BETWEEN ? AND ?
+ AND p.deleted_at IS NULL
+ GROUP BY p.bill_id, substr(p.paid_date, 1, 7)
+ `).all(userId, ...billIds, startDate, endDate);
+
+ const stateRows = db.prepare(`
+ SELECT m.bill_id, m.year, m.month, m.actual_amount, m.is_skipped
+ FROM monthly_bill_state m
+ JOIN bills b ON b.id = m.bill_id
+ WHERE b.user_id = ?
+ AND m.bill_id IN (${placeholders})
+ AND (m.year * 100 + m.month) BETWEEN ? AND ?
+ `).all(
+ userId,
+ ...billIds,
+ rangeMonths[0].year * 100 + rangeMonths[0].month,
+ rangeMonths[rangeMonths.length - 1].year * 100 + rangeMonths[rangeMonths.length - 1].month,
+ );
+
+ const paymentByBillMonth = new Map(paymentRows.map(row => [`${row.bill_id}:${row.month_key}`, Number(row.total) || 0]));
+ const stateByBillMonth = new Map(stateRows.map(row => [`${row.bill_id}:${monthKey(row.year, row.month)}`, row]));
+
+ const monthly_spending = rangeMonths.map(m => {
+ const total = bills.reduce((sum, bill) => sum + (paymentByBillMonth.get(`${bill.id}:${m.key}`) || 0), 0);
+ return { month: m.key, label: m.label, total: Number(total.toFixed(2)) };
+ }).filter(row => row.total > 0);
+
+ const expected_vs_actual = rangeMonths.map(m => {
+ let expected = 0;
+ let actual = 0;
+ let skipped_count = 0;
+ for (const bill of bills) {
+ const state = stateByBillMonth.get(`${bill.id}:${m.key}`);
+ const skipped = !!state?.is_skipped;
+ if (skipped) skipped_count += 1;
+ if (!skipped || parsed.includeSkipped) {
+ actual += paymentByBillMonth.get(`${bill.id}:${m.key}`) || 0;
+ }
+ if (!skipped) {
+ expected += state?.actual_amount ?? bill.expected_amount ?? 0;
+ }
+ }
+ return {
+ month: m.key,
+ label: m.label,
+ expected: Number(expected.toFixed(2)),
+ actual: Number(actual.toFixed(2)),
+ skipped_count,
+ };
+ }).filter(row => row.expected > 0 || row.actual > 0 || row.skipped_count > 0);
+
+ const categoryMap = new Map();
+ for (const bill of bills) {
+ const categoryId = bill.category_id || null;
+ const key = categoryId == null ? 'uncategorized' : String(categoryId);
+ const existing = categoryMap.get(key) || {
+ category_id: categoryId,
+ category_name: bill.category_name || 'Uncategorized',
+ total: 0,
+ };
+ for (const m of rangeMonths) {
+ existing.total += paymentByBillMonth.get(`${bill.id}:${m.key}`) || 0;
+ }
+ categoryMap.set(key, existing);
+ }
+ const category_spend = Array.from(categoryMap.values())
+ .map(row => ({ ...row, total: Number(row.total.toFixed(2)) }))
+ .filter(row => row.total > 0)
+ .sort((a, b) => b.total - a.total);
+
+ const heatmapRows = bills.map(bill => {
+ const cells = rangeMonths.map(m => {
+ const paid = (paymentByBillMonth.get(`${bill.id}:${m.key}`) || 0) > 0;
+ const state = stateByBillMonth.get(`${bill.id}:${m.key}`);
+ const skipped = !!state?.is_skipped;
+ let status = 'no_data';
+ if (skipped) status = 'skipped';
+ else if (paid) status = 'paid';
+ else if (isMonthInPast(m.year, m.month)) status = 'missed';
+ return {
+ month: m.key,
+ label: m.label,
+ status,
+ amount_paid: Number((paymentByBillMonth.get(`${bill.id}:${m.key}`) || 0).toFixed(2)),
+ };
+ });
+ return {
+ bill_id: bill.id,
+ bill_name: bill.name,
+ category_name: bill.category_name || 'Uncategorized',
+ active: !!bill.active,
+ cells: parsed.includeSkipped ? cells : cells.filter(cell => cell.status !== 'skipped'),
+ };
+ });
+
+ res.json({
+ range: { year: parsed.year, month: parsed.month, months: parsed.months, start: startDate, end: endDate },
+ filters: {
+ category_id: parsed.categoryId,
+ bill_id: parsed.billId,
+ include_inactive: parsed.includeInactive,
+ include_skipped: parsed.includeSkipped,
+ },
+ categories,
+ bills: bills.map(b => ({
+ id: b.id,
+ name: b.name,
+ category_id: b.category_id,
+ category_name: b.category_name || 'Uncategorized',
+ active: !!b.active,
+ })),
+ monthly_spending,
+ expected_vs_actual,
+ category_spend,
+ heatmap: {
+ months: rangeMonths.map(({ key, label, year, month }) => ({ key, label, year, month })),
+ rows: heatmapRows,
+ },
+ generated_at: new Date().toISOString(),
+ });
+});
+
+module.exports = router;
diff --git a/routes/calendar.js b/routes/calendar.js
new file mode 100644
index 0000000..06fc9ef
--- /dev/null
+++ b/routes/calendar.js
@@ -0,0 +1,179 @@
+const express = require('express');
+const router = express.Router();
+const { getDb } = require('../db/database');
+const { buildTrackerRow, getCycleRange } = require('../services/statusService');
+
+function clampDay(year, month, day) {
+ const daysInMonth = new Date(year, month, 0).getDate();
+ return Math.min(Math.max(parseInt(day || 1, 10), 1), daysInMonth);
+}
+
+function toDateString(year, month, day) {
+ return `${year}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}`;
+}
+
+function emptyDay(year, month, day) {
+ return {
+ date: toDateString(year, month, day),
+ day,
+ bills_due: [],
+ payments: [],
+ status_summary: {
+ due_count: 0,
+ paid_count: 0,
+ skipped_count: 0,
+ missed_count: 0,
+ total_due: 0,
+ total_paid: 0,
+ },
+ };
+}
+
+// GET /api/calendar?year=2026&month=5
+router.get('/', (req, res) => {
+ const db = getDb();
+ const now = new Date();
+ const year = parseInt(req.query.year || now.getFullYear(), 10);
+ const month = parseInt(req.query.month || now.getMonth() + 1, 10);
+
+ if (isNaN(year) || year < 2000 || year > 2100) {
+ return res.status(400).json({ error: 'year must be a 4-digit integer between 2000 and 2100' });
+ }
+ if (isNaN(month) || month < 1 || month > 12) {
+ return res.status(400).json({ error: 'month must be an integer between 1 and 12' });
+ }
+
+ const today = now.toISOString().slice(0, 10);
+ const daysInMonth = new Date(year, month, 0).getDate();
+ const { start, end } = getCycleRange(year, month);
+ const days = Array.from({ length: daysInMonth }, (_, index) => emptyDay(year, month, index + 1));
+ const dayByDate = new Map(days.map(day => [day.date, day]));
+
+ const bills = db.prepare(`
+ SELECT b.*, c.name AS category_name
+ FROM bills b
+ LEFT JOIN categories c ON b.category_id = c.id
+ WHERE b.active = 1 AND b.user_id = ?
+ ORDER BY b.due_day ASC, b.name ASC
+ `).all(req.user.id);
+
+ const paymentsByBillStmt = db.prepare(`
+ SELECT *
+ FROM payments
+ WHERE bill_id = ? AND paid_date BETWEEN ? AND ?
+ AND deleted_at IS NULL
+ ORDER BY paid_date DESC
+ `);
+
+ const monthlyStateStmt = db.prepare(`
+ SELECT actual_amount, notes, is_skipped
+ FROM monthly_bill_state
+ WHERE bill_id = ? AND year = ? AND month = ?
+ `);
+
+ const payments = db.prepare(`
+ SELECT
+ p.id AS payment_id,
+ p.bill_id,
+ b.name AS bill_name,
+ p.amount,
+ p.paid_date,
+ p.method,
+ p.notes
+ FROM payments p
+ JOIN bills b ON p.bill_id = b.id
+ WHERE b.user_id = ?
+ AND p.paid_date BETWEEN ? AND ?
+ AND p.deleted_at IS NULL
+ ORDER BY p.paid_date ASC, b.name ASC
+ `).all(req.user.id, start, end);
+
+ for (const payment of payments) {
+ const day = dayByDate.get(payment.paid_date);
+ if (day) {
+ day.payments.push({
+ payment_id: payment.payment_id,
+ bill_id: payment.bill_id,
+ bill_name: payment.bill_name,
+ amount: payment.amount,
+ paid_date: payment.paid_date,
+ method: payment.method || null,
+ notes: payment.notes || null,
+ });
+ day.status_summary.total_paid += payment.amount || 0;
+ }
+ }
+
+ const calendarBills = bills.map(bill => {
+ const billPayments = paymentsByBillStmt.all(bill.id, start, end);
+ const row = buildTrackerRow(bill, billPayments, year, month, today);
+ const monthlyState = monthlyStateStmt.get(bill.id, year, month);
+ const actualAmount = monthlyState?.actual_amount ?? null;
+ const isSkipped = !!monthlyState?.is_skipped;
+ const effectiveAmount = actualAmount ?? row.expected_amount;
+ const isPaidByThreshold = row.total_paid > 0 && row.total_paid >= effectiveAmount;
+ const isAutodraft = row.status === 'autodraft';
+ const status = isSkipped
+ ? 'skipped'
+ : isPaidByThreshold
+ ? 'paid'
+ : row.status;
+ const isPaid = status === 'paid' || isAutodraft;
+ const dueDay = clampDay(year, month, bill.due_day);
+ const dueDate = toDateString(year, month, dueDay);
+
+ return {
+ bill_id: bill.id,
+ name: bill.name,
+ due_date: dueDate,
+ due_day: dueDay,
+ expected_amount: row.expected_amount,
+ actual_amount: actualAmount,
+ effective_amount: effectiveAmount,
+ category_name: bill.category_name || null,
+ is_paid: isPaid,
+ is_skipped: isSkipped,
+ paid_amount: row.total_paid || 0,
+ status,
+ };
+ });
+
+ for (const bill of calendarBills) {
+ const day = dayByDate.get(bill.due_date);
+ if (!day) continue;
+
+ day.bills_due.push(bill);
+ day.status_summary.due_count += 1;
+ if (bill.is_paid) day.status_summary.paid_count += 1;
+ if (bill.is_skipped) day.status_summary.skipped_count += 1;
+ if (!bill.is_paid && !bill.is_skipped && (bill.status === 'late' || bill.status === 'missed')) {
+ day.status_summary.missed_count += 1;
+ }
+ if (!bill.is_skipped) day.status_summary.total_due += bill.effective_amount || 0;
+ }
+
+ const activeBills = calendarBills.filter(bill => !bill.is_skipped);
+ const expectedTotal = activeBills.reduce((sum, bill) => sum + (bill.effective_amount || 0), 0);
+ const paidTotal = activeBills.reduce((sum, bill) => sum + (bill.paid_amount || 0), 0);
+ const remainingTotal = Math.max(0, expectedTotal - paidTotal);
+ const paidPercent = expectedTotal > 0 ? Math.min(100, Math.round((paidTotal / expectedTotal) * 100)) : 0;
+
+ res.json({
+ year,
+ month,
+ today,
+ days,
+ summary: {
+ expected_total: expectedTotal,
+ paid_total: paidTotal,
+ remaining_total: remainingTotal,
+ paid_percent: paidPercent,
+ bill_count: activeBills.length,
+ paid_count: activeBills.filter(bill => bill.is_paid).length,
+ skipped_count: calendarBills.filter(bill => bill.is_skipped).length,
+ missed_count: activeBills.filter(bill => bill.status === 'late' || bill.status === 'missed').length,
+ },
+ });
+});
+
+module.exports = router;
diff --git a/server.js b/server.js
index 02bf9b1..0401dc4 100644
--- a/server.js
+++ b/server.js
@@ -46,6 +46,8 @@ app.use('/api/bills', requireAuth, requireUser, require('./routes/bills'
app.use('/api/payments', requireAuth, requireUser, require('./routes/payments'));
app.use('/api/categories', requireAuth, requireUser, require('./routes/categories'));
app.use('/api/settings', requireAuth, requireUser, require('./routes/settings'));
+app.use('/api/calendar', requireAuth, requireUser, require('./routes/calendar'));
+app.use('/api/analytics', requireAuth, requireUser, require('./routes/analytics'));
app.use('/api/notifications', requireAuth, require('./routes/notifications'));
app.use('/api/status', requireAuth, require('./routes/status'));
app.use('/api/version', require('./routes/version')); // public