Open-source personal finance manager. Self-hosted, privacy-first.
feat: add quarterly recurring transactions (#499)
seraphblade2010d5e1a80bb20f
diff --git a/backend/app/models/recurring_transaction.py b/backend/app/models/recurring_transaction.pyindex a5ef42ac..becc8276 100644--- a/backend/app/models/recurring_transaction.py+++ b/backend/app/models/recurring_transaction.py@@ -34,7 +34,7 @@ class RecurringTransaction(Base):amount: Mapped[Decimal] = mapped_column(Numeric(precision=15, scale=2))currency: Mapped[str] = mapped_column(String(3), default="USD")type: Mapped[str] = mapped_column(String(10)) # debit, credit- frequency: Mapped[str] = mapped_column(String(20)) # monthly, weekly, yearly+ frequency: Mapped[str] = mapped_column(String(20)) # weekly, monthly, quarterly, yearlyday_of_month: Mapped[Optional[int]] = mapped_column(Integer, nullable=True)start_date: Mapped[date] = mapped_column(Date)end_date: Mapped[Optional[date]] = mapped_column(Date, nullable=True)diff --git a/backend/app/schemas/recurring_transaction.py b/backend/app/schemas/recurring_transaction.pyindex 8fccd313..e020ee33 100644--- a/backend/app/schemas/recurring_transaction.py+++ b/backend/app/schemas/recurring_transaction.py@@ -11,7 +11,7 @@ class RecurringTransactionCreate(BaseModel):amount: Decimalcurrency: str = "USD"type: str # debit, credit- frequency: str # monthly, weekly, yearly+ frequency: str # weekly, monthly, quarterly, yearlyday_of_month: Optional[int] = Nonestart_date: _Dateend_date: Optional[_Date] = None@@ -26,7 +26,7 @@ class RecurringTransactionUpdate(BaseModel):amount: Optional[Decimal] = Nonecurrency: Optional[str] = Nonetype: Optional[str] = None- frequency: Optional[str] = None+ frequency: Optional[str] = None # weekly, monthly, quarterly, yearlyday_of_month: Optional[int] = Nonestart_date: Optional[_Date] = Noneend_date: Optional[_Date] = Nonediff --git a/backend/app/services/recurring_transaction_service.py b/backend/app/services/recurring_transaction_service.pyindex 389e67c6..e756def7 100644--- a/backend/app/services/recurring_transaction_service.py+++ b/backend/app/services/recurring_transaction_service.py@@ -134,30 +134,40 @@ async def delete_recurring_transaction(return True+def _advance_months(current: date, months: int, intended_day: int) -> date:+ """Advance by calendar months, clamping only in a shorter target month."""+ month_index = current.month - 1 + months+ year = current.year + month_index // 12+ month = month_index % 12 + 1+ day = min(intended_day, calendar.monthrange(year, month)[1])+ return date(year, month, day)++def _advance_date(current: date, frequency: str, intended_day: Optional[int] = None,) -> date:"""Advance a date by the given frequency.- For monthly/yearly, ``intended_day`` is the day the user actually wants- (e.g. 31). We cap it to the target month's length so Feb clamps to 28/29,- but subsequent months recover to 31/30 instead of sticking at 28.- Falls back to ``current.day`` when not provided."""+ For monthly, quarterly, and yearly recurrences, ``intended_day`` is the day+ the user actually wants (e.g. 31). We cap it to the target month's length+ so short months clamp, but subsequent occurrences recover to the intended+ day when it exists again. Falls back to ``current.day`` when not provided.+ """if frequency == "weekly":return current + timedelta(weeks=1)+target_day = intended_day if intended_day else current.day+ if frequency == "monthly":+ return _advance_months(current, 1, target_day)+ if frequency == "quarterly":+ return _advance_months(current, 3, target_day)if frequency == "yearly":year = current.year + 1day = min(target_day, calendar.monthrange(year, current.month)[1])return date(year, current.month, day)- # monthly (default)- month = current.month + 1- year = current.year- if month > 12:- month = 1- year += 1- day = min(target_day, calendar.monthrange(year, month)[1])- return date(year, month, day)++ # Preserve the existing monthly fallback for unknown legacy values.+ return _advance_months(current, 1, target_day)def get_occurrences_in_range(diff --git a/backend/mcp_server/tools/proposals.py b/backend/mcp_server/tools/proposals.pyindex 1f0d4800..f6c337f1 100644--- a/backend/mcp_server/tools/proposals.py+++ b/backend/mcp_server/tools/proposals.py@@ -533,7 +533,8 @@ async def propose_create_transaction(description=_PROPOSAL_PREFACE + ("Build a preview for adding a recurring transaction / subscription ""(e.g. 'Netflix R$55 every month on the 10th'). Frequency is one "- "of weekly/monthly/yearly. For monthly use day_of_month (1-31)."+ "of weekly/monthly/quarterly/yearly. For monthly or quarterly use "+ "day_of_month (1-31)."),parameters={"type": "object",@@ -541,8 +542,8 @@ async def propose_create_transaction("description": {"type": "string", "minLength": 1, "maxLength": 500},"amount": {"type": "number", "exclusiveMinimum": 0},"type": {"type": "string", "enum": ["debit", "credit"]},- "frequency": {"type": "string", "enum": ["weekly", "monthly", "yearly"]},- "day_of_month": {"type": "integer", "minimum": 1, "maximum": 31, "description": "Required for monthly"},+ "frequency": {"type": "string", "enum": ["weekly", "monthly", "quarterly", "yearly"]},+ "day_of_month": {"type": "integer", "minimum": 1, "maximum": 31, "description": "Required for monthly or quarterly"},"start_date": {"type": "string", "format": "date", "description": "Defaults to today"},"end_date": {"type": "string", "format": "date"},"account_id": {"type": "string", "format": "uuid"},@@ -572,8 +573,8 @@ async def propose_create_recurring_transaction(currency: str | None = None,apply: bool = False,) -> dict[str, Any]:- if frequency == "monthly" and not day_of_month:- return {"error": "day_of_month is required for monthly frequency"}+ if frequency in ("monthly", "quarterly") and not day_of_month:+ return {"error": "day_of_month is required for monthly or quarterly frequency"}ws_id = await resolve_workspace_id(session, ctx)acc = (await session.execute(select(Account).where(Account.id == parse_uuid(account_id), Account.workspace_id == ws_id)@@ -648,7 +649,7 @@ async def propose_create_recurring_transaction("recurring_id": {"type": "string", "format": "uuid"},"description": {"type": "string", "minLength": 1, "maxLength": 500},"amount": {"type": "number", "exclusiveMinimum": 0},- "frequency": {"type": "string", "enum": ["weekly", "monthly", "yearly"]},+ "frequency": {"type": "string", "enum": ["weekly", "monthly", "quarterly", "yearly"]},"day_of_month": {"type": "integer", "minimum": 1, "maximum": 31},"end_date": {"type": "string", "format": "date"},"category_id": {"type": "string", "format": "uuid"},diff --git a/backend/tests/test_recurring_api.py b/backend/tests/test_recurring_api.pyindex 32d28146..a1b4b92c 100644--- a/backend/tests/test_recurring_api.py+++ b/backend/tests/test_recurring_api.py@@ -78,6 +78,30 @@ async def test_create_recurring_skip_first_monthly(client, auth_headers, test_acassert data["next_occurrence"] == "2026-02-15"+async def test_create_recurring_skip_first_quarterly(client, auth_headers, test_account):+ """Quarterly is accepted by the API and skip_first advances three calendar months."""+ response = await client.post(+ "/api/recurring-transactions",+ json={+ "description": "Insurance",+ "amount": 300.00,+ "currency": "BRL",+ "type": "debit",+ "frequency": "quarterly",+ "day_of_month": 31,+ "start_date": "2026-01-31",+ "skip_first": True,+ "account_id": str(test_account.id),+ },+ headers=auth_headers,+ )+ assert response.status_code == 201+ data = response.json()+ assert data["frequency"] == "quarterly"+ assert data["next_occurrence"] == "2026-04-30"++@pytest.mark.asyncioasync def test_generate_pending_creates_transactions(client, auth_headers, test_account):"""Generate pending creates transactions and advances next_occurrence."""diff --git a/backend/tests/test_recurring_match.py b/backend/tests/test_recurring_match.pyindex d62065fd..f39a4c00 100644--- a/backend/tests/test_recurring_match.py+++ b/backend/tests/test_recurring_match.py@@ -197,6 +197,21 @@ async def test_advance_past_moves_pointer(session, test_user, test_workspace, acassert bill.next_occurrence == date(2025, 2, 10)+async def test_advance_past_moves_quarterly_pointer(session, test_user, test_workspace, account):+ bill = await _make_bill(+ session,+ test_workspace,+ test_user,+ account,+ frequency="quarterly",+ day_of_month=31,+ start_date=date(2025, 1, 31),+ )+ rms.advance_past(bill, date(2025, 1, 31))+ assert bill.next_occurrence == date(2025, 4, 30)++@pytest.mark.asyncioasync def test_advance_past_deactivates_past_end_date(session, test_user, test_workspace, account):bill = await _make_bill(diff --git a/backend/tests/test_recurring_transaction_service.py b/backend/tests/test_recurring_transaction_service.pyindex 7d68b03c..a4463846 100644--- a/backend/tests/test_recurring_transaction_service.py+++ b/backend/tests/test_recurring_transaction_service.py@@ -259,6 +259,29 @@ def test_advance_date_yearly_intended_day_leap_recovery():assert y4 == date(2028, 2, 29)+def test_advance_date_quarterly():+ assert _advance_date(date(2026, 1, 15), "quarterly") == date(2026, 4, 15)+ assert _advance_date(date(2026, 11, 15), "quarterly") == date(2027, 2, 15)+++def test_advance_date_quarterly_intended_day_recovers_after_clamping():+ april = _advance_date(date(2026, 1, 31), "quarterly", intended_day=31)+ assert april == date(2026, 4, 30)+ july = _advance_date(april, "quarterly", intended_day=31)+ assert july == date(2026, 7, 31)+ october = _advance_date(july, "quarterly", intended_day=31)+ assert october == date(2026, 10, 31)+ january = _advance_date(october, "quarterly", intended_day=31)+ assert january == date(2027, 1, 31)+++def test_advance_date_quarterly_leap_year_clamping_recovers():+ february = _advance_date(date(2023, 11, 30), "quarterly", intended_day=30)+ assert february == date(2024, 2, 29)+ may = _advance_date(february, "quarterly", intended_day=30)+ assert may == date(2024, 5, 30)++# ---------------------------------------------------------------------------# get_occurrences_in_range# ---------------------------------------------------------------------------@@ -367,6 +390,35 @@ def test_get_occurrences_in_range_monthly_day_29_does_not_drift():]+def test_get_occurrences_in_range_quarterly():+ occurrences = get_occurrences_in_range(+ start=date(2026, 1, 31),+ frequency="quarterly",+ end_date=None,+ range_start=date(2026, 1, 1),+ range_end=date(2027, 2, 1),+ intended_day=31,+ )+ assert occurrences == [+ date(2026, 1, 31),+ date(2026, 4, 30),+ date(2026, 7, 31),+ date(2026, 10, 31),+ date(2027, 1, 31),+ ]+++def test_get_occurrences_in_range_quarterly_respects_end_date():+ occurrences = get_occurrences_in_range(+ start=date(2026, 1, 15),+ frequency="quarterly",+ end_date=date(2026, 7, 1),+ range_start=date(2026, 1, 1),+ range_end=date(2027, 1, 1),+ )+ assert occurrences == [date(2026, 1, 15), date(2026, 4, 15)]++# ---------------------------------------------------------------------------# generate_pending# ---------------------------------------------------------------------------@@ -406,6 +458,48 @@ async def test_generate_pending(session: AsyncSession, test_user, test_workspaceassert rec.next_occurrence == date(2025, 4, 1)+async def test_generate_pending_quarterly_respects_end_date(+ session: AsyncSession, test_user, test_workspace, test_account_for_recurring+):+ rec = await create_recurring_transaction(+ session,+ test_workspace.id,+ test_user.id,+ RecurringTransactionCreate(+ description="Quarterly Insurance",+ amount=Decimal("300"),+ type="debit",+ frequency="quarterly",+ day_of_month=30,+ start_date=date(2023, 11, 30),+ end_date=date(2024, 5, 30),+ account_id=test_account_for_recurring.id,+ ),+ )++ count = await generate_pending(session, test_user.id, up_to=date(2024, 12, 31))+ assert count == 3++ result = await session.execute(+ select(Transaction)+ .where(+ Transaction.recurring_transaction_id == rec.id,+ Transaction.source == "recurring",+ )+ .order_by(Transaction.date)+ )+ assert [transaction.date for transaction in result.scalars()] == [+ date(2023, 11, 30),+ date(2024, 2, 29),+ date(2024, 5, 30),+ ]++ await session.refresh(rec)+ assert rec.next_occurrence == date(2024, 8, 30)+ assert rec.is_active is False++@pytest.mark.asyncioasync def test_generate_pending_deactivates_past_end_date(session: AsyncSession, test_user, test_workspace, test_account_for_recurringdiff --git a/frontend/src/components/transaction-dialog.tsx b/frontend/src/components/transaction-dialog.tsxindex 2e3d6170..1baae33a 100644--- a/frontend/src/components/transaction-dialog.tsx+++ b/frontend/src/components/transaction-dialog.tsx@@ -378,7 +378,7 @@ function TransactionForm({!!transaction && (seed?.amount_primary != null || seed?.fx_rate_used != null))const [isRecurring, setIsRecurring] = useState(false)- const [frequency, setFrequency] = useState<'monthly' | 'weekly' | 'yearly'>('monthly')+ const [frequency, setFrequency] = useState<RecurringTransaction['frequency']>('monthly')const [endDate, setEndDate] = useState('')// Optional split-with-group payload. `null` = leave splits as-is on// update, or no splits on create. The dedicated section component@@ -1053,9 +1053,10 @@ function TransactionForm({<selectclassName="w-full border border-border rounded-md px-3 py-2 text-sm bg-background focus:outline-none focus-visible:ring-ring/30 focus-visible:ring-[2px]"value={frequency}- onChange={(e) => setFrequency(e.target.value as 'monthly' | 'weekly' | 'yearly')}+ onChange={(e) => setFrequency(e.target.value as RecurringTransaction['frequency'])}><option value="monthly">{t('recurring.monthly')}</option>+ <option value="quarterly">{t('recurring.quarterly')}</option><option value="weekly">{t('recurring.weekly')}</option><option value="yearly">{t('recurring.yearly')}</option></select>diff --git a/frontend/src/locales/de.json b/frontend/src/locales/de.jsonindex fc3a1838..9a9aa9a5 100644--- a/frontend/src/locales/de.json+++ b/frontend/src/locales/de.json@@ -778,6 +778,7 @@"income": "Einnahme","frequency": "Häufigkeit","monthly": "Monatlich",+ "quarterly": "Vierteljährlich","weekly": "Wöchentlich","yearly": "Jährlich","dayOfMonth": "Tag des Monats",diff --git a/frontend/src/locales/en.json b/frontend/src/locales/en.jsonindex 5185e48e..77de71d3 100644--- a/frontend/src/locales/en.json+++ b/frontend/src/locales/en.json@@ -778,6 +778,7 @@"income": "Income","frequency": "Frequency","monthly": "Monthly",+ "quarterly": "Quarterly","weekly": "Weekly","yearly": "Yearly","dayOfMonth": "Day of month",diff --git a/frontend/src/locales/es.json b/frontend/src/locales/es.jsonindex 210a4336..ce3a20dc 100644--- a/frontend/src/locales/es.json+++ b/frontend/src/locales/es.json@@ -778,6 +778,7 @@"income": "Ingreso","frequency": "Frecuencia","monthly": "Mensual",+ "quarterly": "Trimestral","weekly": "Semanal","yearly": "Anual","dayOfMonth": "Día del mes",diff --git a/frontend/src/locales/fr.json b/frontend/src/locales/fr.jsonindex cbecf13a..b6a71a1f 100644--- a/frontend/src/locales/fr.json+++ b/frontend/src/locales/fr.json@@ -778,6 +778,7 @@"income": "Revenu","frequency": "Fréquence","monthly": "Mensuelle",+ "quarterly": "Trimestrielle","weekly": "Hebdomadaire","yearly": "Annuelle","dayOfMonth": "Jour du mois",diff --git a/frontend/src/locales/it.json b/frontend/src/locales/it.jsonindex 06eeb736..55792db0 100644--- a/frontend/src/locales/it.json+++ b/frontend/src/locales/it.json@@ -778,6 +778,7 @@"income": "Entrata","frequency": "Frequenza","monthly": "Mensile",+ "quarterly": "Trimestrale","weekly": "Settimanale","yearly": "Annuale","dayOfMonth": "Giorno del mese",diff --git a/frontend/src/locales/pl.json b/frontend/src/locales/pl.jsonindex 832407f9..37e8894c 100644--- a/frontend/src/locales/pl.json+++ b/frontend/src/locales/pl.json@@ -820,6 +820,7 @@"income": "Przychód","frequency": "Częstotliwość","monthly": "Miesięcznie",+ "quarterly": "Kwartalnie","weekly": "Tygodniowo","yearly": "Rocznie","dayOfMonth": "Dzień miesiąca",diff --git a/frontend/src/locales/pt-BR.json b/frontend/src/locales/pt-BR.jsonindex fc54bf9d..8c3ac00c 100644--- a/frontend/src/locales/pt-BR.json+++ b/frontend/src/locales/pt-BR.json@@ -778,6 +778,7 @@"income": "Entrada","frequency": "Frequência","monthly": "Mensal",+ "quarterly": "Trimestral","weekly": "Semanal","yearly": "Anual","dayOfMonth": "Dia do mês",diff --git a/frontend/src/locales/pt-PT.json b/frontend/src/locales/pt-PT.jsonindex b149c62f..e885d8d4 100644--- a/frontend/src/locales/pt-PT.json+++ b/frontend/src/locales/pt-PT.json@@ -778,6 +778,7 @@"income": "Entrada","frequency": "Frequência","monthly": "Mensal",+ "quarterly": "Trimestral","weekly": "Semanal","yearly": "Anual","dayOfMonth": "Dia do mês",diff --git a/frontend/src/locales/ru.json b/frontend/src/locales/ru.jsonindex 4de871e5..2adac992 100644--- a/frontend/src/locales/ru.json+++ b/frontend/src/locales/ru.json@@ -778,6 +778,7 @@"income": "Доход","frequency": "Частота","monthly": "Ежемесячно",+ "quarterly": "Ежеквартально","weekly": "Еженедельно","yearly": "Ежегодно","dayOfMonth": "День месяца",diff --git a/frontend/src/locales/uk.json b/frontend/src/locales/uk.jsonindex dbdb2cb5..98e4cd86 100644--- a/frontend/src/locales/uk.json+++ b/frontend/src/locales/uk.json@@ -778,6 +778,7 @@"income": "Дохід","frequency": "Частота","monthly": "Щомісяця",+ "quarterly": "Щоквартально","weekly": "Щотижня","yearly": "Щороку","dayOfMonth": "День місяця",diff --git a/frontend/src/pages/recurring.tsx b/frontend/src/pages/recurring.tsxindex 3bd74841..d42837a5 100644--- a/frontend/src/pages/recurring.tsx+++ b/frontend/src/pages/recurring.tsx@@ -137,7 +137,7 @@ function RecurringTab() {})const frequencyLabel = (f: string) => {- const map: Record<string, string> = { monthly: t('recurring.monthly'), weekly: t('recurring.weekly'), yearly: t('recurring.yearly') }+ const map: Record<string, string> = { monthly: t('recurring.monthly'), quarterly: t('recurring.quarterly'), weekly: t('recurring.weekly'), yearly: t('recurring.yearly') }return map[f] ?? f}@@ -359,13 +359,14 @@ function RecurringForm({<div className="grid grid-cols-2 gap-4"><div className="space-y-2"><Label>{t('recurring.frequency')}</Label>- <select className={selectClass} value={frequency} onChange={(e) => setFrequency(e.target.value as 'monthly' | 'weekly' | 'yearly')}>+ <select className={selectClass} value={frequency} onChange={(e) => setFrequency(e.target.value as RecurringTransaction['frequency'])}><option value="monthly">{t('recurring.monthly')}</option>+ <option value="quarterly">{t('recurring.quarterly')}</option><option value="weekly">{t('recurring.weekly')}</option><option value="yearly">{t('recurring.yearly')}</option></select></div>- {frequency === 'monthly' && (+ {(frequency === 'monthly' || frequency === 'quarterly') && (<div className="space-y-2"><Label>{t('recurring.dayOfMonth')}</Label><Input type="number" min="1" max="31" value={dayOfMonth} onChange={(e) => setDayOfMonth(e.target.value)} />diff --git a/frontend/src/types/index.ts b/frontend/src/types/index.tsindex 85f4c28b..12687a81 100644--- a/frontend/src/types/index.ts+++ b/frontend/src/types/index.ts@@ -431,7 +431,7 @@ export interface RecurringTransaction {amount: numbercurrency: stringtype: 'debit' | 'credit'- frequency: 'monthly' | 'weekly' | 'yearly'+ frequency: 'monthly' | 'quarterly' | 'weekly' | 'yearly'day_of_month: number | nullstart_date: stringend_date: string | null