Open-source personal finance manager. Self-hosted, privacy-first.
fix(pluggy): date future installments in the month they are billed (#1111)
Gustavo Marques da Silva528f6d81823c
diff --git a/backend/app/providers/pluggy.py b/backend/app/providers/pluggy.pyindex dae0bfb0..d90e4e19 100644--- a/backend/app/providers/pluggy.py+++ b/backend/app/providers/pluggy.py@@ -1,4 +1,5 @@import asyncio+import calendarimport hashlibimport jsonimport logging@@ -67,6 +68,14 @@ def _compe_from_transfer_number(transfer_number) -> Optional[str]:return code.zfill(3) if code.isdigit() else None+def _add_months(d: date, months: int) -> date:+ """Advance a date by N months, clamping the day to the target month's length."""+ month_index = d.month - 1 + months+ year = d.year + month_index // 12+ month = month_index % 12 + 1+ return date(year, month, min(d.day, calendar.monthrange(year, month)[1]))++# Public, community-maintained mirror of the Bacen (Central Bank) COMPE# participant registry — free, no API key, no rate limits seen in practice.# https://brasilapi.com.br/api/banks/v1/{code}@@ -620,6 +629,24 @@ class PluggyProvider(BankProvider):inst_purchase_date = date.fromisoformat(str(inst_purchase_date_raw)[:10])except ValueError:inst_purchase_date = None+ # Mercado Pago reports every installment not billed yet+ # with the purchase timestamp as its date, so a 10x+ # purchase lands whole in the month it was made. The+ # tell is `date` being an exact copy of `purchaseDate`,+ # time included: connectors that schedule installments+ # (Nubank) send a date of their own, even on the same+ # day. Such a row moves to the purchase day N-1 months+ # on, where Nubank puts the same installment. Posted rows+ # are never moved: Itaú sends billed installments with a+ # purchaseDate equal to their own charge date.+ if (+ status == "pending"+ and isinstance(inst_number, int)+ and inst_number > 1+ and inst_purchase_date is not None+ and txn.get("date") == inst_purchase_date_raw+ ):+ txn_date = _add_months(inst_purchase_date, inst_number - 1)inst_total_amount_dec = (Decimal(str(abs(inst_total_amount)))if inst_total_amount is not Nonediff --git a/backend/tests/test_providers_pluggy.py b/backend/tests/test_providers_pluggy.pyindex 1bb6840c..863f82f0 100644--- a/backend/tests/test_providers_pluggy.py+++ b/backend/tests/test_providers_pluggy.py@@ -286,6 +286,85 @@ async def test_parser_missing_purchase_date_only():assert tx.installment_purchase_date is None+# ---------------------------------------------------------------------------+# Future installments reported at the purchase date (Mercado Pago)+# ---------------------------------------------------------------------------+++def _installment(number: int, total: int, txn_date: str, purchase_date: str) -> dict:+ return {+ "id": f"tx-{number}",+ "description": "MERCADOLIVRE*MERCADOLIVRE",+ "amount": -56.99,+ "date": txn_date,+ "type": "DEBIT",+ "status": "PENDING",+ "creditCardMetadata": {+ "installmentNumber": number,+ "totalInstallments": total,+ "purchaseDate": purchase_date,+ },+ }+++async def test_future_installment_at_purchase_date_moves_to_its_month():+ """Installment 5 of a 6 June purchase belongs in October, not June."""+ result = await _fetch([+ _installment(5, 10, "2026-06-06T13:26:40.000Z", "2026-06-06T13:26:40.000Z"),+ ])+ assert result[0].date == date(2026, 10, 6)+ assert result[0].installment_purchase_date == date(2026, 6, 6)+++async def test_future_installment_crosses_into_the_next_year():+ result = await _fetch([+ _installment(18, 18, "2025-11-01T14:49:23.000Z", "2025-11-01T14:49:23.000Z"),+ ])+ assert result[0].date == date(2027, 4, 1)+++async def test_future_installment_day_is_clamped_to_a_shorter_month():+ result = await _fetch([+ _installment(2, 3, "2026-01-31", "2026-01-31"),+ ])+ assert result[0].date == date(2026, 2, 28)+++async def test_first_installment_keeps_the_purchase_date():+ result = await _fetch([+ _installment(1, 10, "2026-06-06T13:26:40.000Z", "2026-06-06T13:26:40.000Z"),+ ])+ assert result[0].date == date(2026, 6, 6)+++async def test_installment_the_connector_already_dated_is_kept():+ """A date of the connector's own is left alone, even when it is not+ exactly the purchase day N-1 months on."""+ result = await _fetch([+ _installment(2, 10, "2026-07-12T03:00:00.000Z", "2026-06-06T13:26:40.000Z"),+ ])+ assert result[0].date == date(2026, 7, 12)+++async def test_scheduled_installment_on_its_purchase_day_is_kept():+ """Nubank sometimes reports a scheduled installment with a purchaseDate on+ the installment's own day. Same day, different timestamp: it is already+ in its month, and moving it would push it N-1 months too far."""+ result = await _fetch([+ _installment(3, 5, "2026-11-10T03:00:00.000Z", "2026-11-10T00:00:00.001Z"),+ ])+ assert result[0].date == date(2026, 11, 10)+++async def test_posted_installment_at_its_purchase_date_is_kept():+ """Itaú sends billed installments with a purchaseDate equal to their own+ charge date. A posted row is the bank's record of when it was charged."""+ installment = _installment(8, 12, "2026-07-09T03:00:00.000Z", "2026-07-09T03:00:00.000Z")+ installment["status"] = "POSTED"+ result = await _fetch([installment])+ assert result[0].date == date(2026, 7, 9)++# ---------------------------------------------------------------------------# v2 cursor pagination (GET /v2/transactions)# ---------------------------------------------------------------------------