Open-source personal finance manager. Self-hosted, privacy-first.
import uuid
from datetime import date
from typing import Optional
from fastapi import APIRouter, Depends, HTTPException, Query
from sqlalchemy.ext.asyncio import AsyncSession
from app.core.app_clock import app_today
from app.core.database import get_async_session
from app.core.workspace_context import WorkspaceContext, current_workspace
from app.schemas.report import ReportDataRange, ReportResponse
from app.services import report_service
router = APIRouter(prefix="/api/reports", tags=["reports"])
# Cap the user-picked custom range so wide windows can't tie up the DB with
# per-day snapshot fan-out. Ten years covers every realistic personal-finance
# question and stays inside the existing daily-interval budget.
_MAX_CUSTOM_RANGE_YEARS = 10
def _add_years(value: date, years: int) -> date:
"""Add whole calendar years to a date.
Clamps Feb 29 to Feb 28 when the target year isn't a leap year, so the
result is always a valid calendar date rather than raising.
"""
try:
return value.replace(year=value.year + years)
except ValueError:
return date(value.year + years, 2, 28)
def _financial_year_start_month(tax_jurisdiction: str | None) -> int:
"""Return the first month of the workspace's financial year."""
return 4 if (tax_jurisdiction or "").upper() == "IN" else 1
def _reject_unsupported_fiscal_year_report(
period: str | None, interval: str, financial_year_start_month: int
) -> None:
if period == "ytd" and interval == "yearly" and financial_year_start_month != 1:
raise HTTPException(
status_code=422,
detail="Yearly YTD reports are not supported for non-calendar financial years",
)
def _resolve_custom_range(
start_date: date | None, end_date: date | None
) -> tuple[date | None, date | None]:
"""Validate a user-supplied custom range and return the (start, end) pair.
Both endpoints must be provided together; the range must be non-empty,
end no later than today and stay within :data:`_MAX_CUSTOM_RANGE_YEARS`
calendar years of start_date. Returns ``(None, None)`` when neither is
set, so callers can use presets.
"""
if start_date is None and end_date is None:
return None, None
if start_date is None or end_date is None:
raise HTTPException(
status_code=422,
detail="start_date and end_date must be provided together",
)
if end_date < start_date:
raise HTTPException(
status_code=422,
detail="end_date must be on or after start_date",
)
# The app's calendar, not the host clock: the workspace's request runs
# on its own timezone (see the `current_workspace` dependency), and the
# service below builds the same window from `app_today()`. Comparing
# against a different calendar would reject the workspace's own today
# or accept a date the workspace has not reached yet.
if end_date > app_today():
raise HTTPException(
status_code=422,
detail="end_date must be on or before today",
)
max_end_date = _add_years(start_date, _MAX_CUSTOM_RANGE_YEARS)
if end_date > max_end_date:
raise HTTPException(
status_code=422,
detail=(
f"Custom range is too wide (max {_MAX_CUSTOM_RANGE_YEARS} years)"
),
)
return start_date, end_date
@router.get("/data-range", response_model=ReportDataRange)
async def get_data_range(
ctx: WorkspaceContext = Depends(current_workspace),
session: AsyncSession = Depends(get_async_session),
):
"""The span of transaction data this workspace actually has.
The Reports page builds its year picker from these bounds (issue #765).
Opening balances are excluded: their dates are synthetic. Both bounds
are null when the workspace has no reportable transactions.
"""
min_date, max_date = await report_service.get_report_data_range(
session, ctx.workspace.id
)
return ReportDataRange(
min_date=min_date.isoformat() if min_date else None,
max_date=max_date.isoformat() if max_date else None,
)
@router.get("/net-worth", response_model=ReportResponse)
async def get_net_worth(
months: int = Query(12, ge=1, le=24),
interval: str = Query("monthly", pattern="^(daily|weekly|monthly|yearly)$"),
account_ids: Optional[list[uuid.UUID]] = Query(None),
asset_group_ids: Optional[list[uuid.UUID]] = Query(None),
period: str | None = Query(None, pattern="^ytd$"),
start_date: date | None = Query(None),
end_date: date | None = Query(None),
ctx: WorkspaceContext = Depends(current_workspace),
session: AsyncSession = Depends(get_async_session),
):
financial_year_start_month = _financial_year_start_month(ctx.workspace.tax_jurisdiction)
custom_start, custom_end = _resolve_custom_range(start_date, end_date)
effective_period = None if custom_start is not None else period
_reject_unsupported_fiscal_year_report(
effective_period, interval, financial_year_start_month
)
return await report_service.get_net_worth_report(
session, ctx.workspace.id, ctx.user_id, months, interval, ctx.user.primary_currency,
account_ids=account_ids, asset_group_ids=asset_group_ids, period=effective_period,
financial_year_start_month=financial_year_start_month,
start_date=custom_start, end_date=custom_end,
)
@router.get("/income-expenses", response_model=ReportResponse)
async def get_income_expenses(
months: int = Query(12, ge=1, le=24),
interval: str = Query("monthly", pattern="^(daily|weekly|monthly|yearly)$"),
account_ids: Optional[list[uuid.UUID]] = Query(None),
period: str | None = Query(None, pattern="^ytd$"),
days: Optional[int] = Query(None, ge=1, le=730),
start_date: date | None = Query(None),
end_date: date | None = Query(None),
ctx: WorkspaceContext = Depends(current_workspace),
session: AsyncSession = Depends(get_async_session),
):
"""`days` overrides `months` with an exact rolling window ending today.
Alternatively `start_date`/`end_date` (both required together) pin the
window to an explicit historical calendar range, overriding `months`,
`period`, and `days`. Custom ranges include actuals only, without estimates.
"""
financial_year_start_month = _financial_year_start_month(ctx.workspace.tax_jurisdiction)
custom_start, custom_end = _resolve_custom_range(start_date, end_date)
effective_period = None if custom_start is not None else period
_reject_unsupported_fiscal_year_report(
effective_period, interval, financial_year_start_month
)
return await report_service.get_income_expenses_report(
session, ctx.workspace.id, ctx.user_id, months, interval, ctx.user.primary_currency,
account_ids=account_ids, period=effective_period, days=days,
financial_year_start_month=financial_year_start_month,
start_date=custom_start, end_date=custom_end,
)
@router.get("/cash-flow", response_model=ReportResponse)
async def get_cash_flow(
months: int = Query(6, ge=1, le=12),
interval: str = Query("daily", pattern="^(daily|weekly|monthly)$"),
baseline: bool = Query(False),
account_ids: Optional[list[uuid.UUID]] = Query(None),
ctx: WorkspaceContext = Depends(current_workspace),
session: AsyncSession = Depends(get_async_session),
):
return await report_service.get_cash_flow_report(
session, ctx.workspace.id, ctx.user_id, months, interval, ctx.user.primary_currency,
baseline=baseline, account_ids=account_ids,
)