Open-source personal finance manager. Self-hosted, privacy-first.
fix: deduplicate Pluggy shared credit balance (#682)
Victor Hugo dos Santos965316fcb754
diff --git a/backend/alembic/versions/090_account_shared_balance_group.py b/backend/alembic/versions/090_account_shared_balance_group.pynew file mode 100644index 00000000..f3460013--- /dev/null+++ b/backend/alembic/versions/090_account_shared_balance_group.py@@ -0,0 +1,21 @@+from typing import Sequence, Union++import sqlalchemy as sa+from alembic import op+++revision: str = "090"+down_revision: Union[str, None] = "089"+branch_labels: Union[str, Sequence[str], None] = None+depends_on: Union[str, Sequence[str], None] = None+++def upgrade() -> None:+ op.add_column(+ "accounts",+ sa.Column("shared_balance_group", sa.String(length=128), nullable=True),+ )+++def downgrade() -> None:+ op.drop_column("accounts", "shared_balance_group")diff --git a/backend/app/models/account.py b/backend/app/models/account.pyindex d407fd2f..f8ffc664 100644--- a/backend/app/models/account.py+++ b/backend/app/models/account.py@@ -41,6 +41,7 @@ class Account(Base):minimum_payment: Mapped[Optional[Decimal]] = mapped_column(Numeric(precision=15, scale=2), nullable=True)card_brand: Mapped[Optional[str]] = mapped_column(String(50), nullable=True)card_level: Mapped[Optional[str]] = mapped_column(String(50), nullable=True)+ shared_balance_group: Mapped[Optional[str]] = mapped_column(String(128), nullable=True)# The institution this account is actually at. One connection can span# several (SimpleFIN — issue #345); null falls back to the connection's# own institution_name/logo_url. Eager (selectin) because serializationdiff --git a/backend/app/providers/base.py b/backend/app/providers/base.pyindex 54bad0f8..b173db56 100644--- a/backend/app/providers/base.py+++ b/backend/app/providers/base.py@@ -70,6 +70,7 @@ class AccountData:# provider exposes one. Disambiguates accounts a bank reports under an# identical name (issue #408). Never the full identifier — see mask_last4.masked_number: Optional[str] = None+ shared_balance_group: Optional[str] = None# Per-account institution override (SimpleFIN — issue #345). None = same# as connection. The external id is the provider's stable org id# (SimpleFIN conn_id) so a renamed bank updates its row instead ofdiff --git a/backend/app/providers/pluggy.py b/backend/app/providers/pluggy.pyindex b7708ddb..e51cbe1a 100644--- a/backend/app/providers/pluggy.py+++ b/backend/app/providers/pluggy.py@@ -1,4 +1,6 @@import asyncio+import hashlib+import jsonimport loggingimport timefrom datetime import date@@ -104,6 +106,40 @@ def _decimal_or_none(value) -> Optional[Decimal]:return None+def _consolidated_credit_balance_group(+ credit_data: dict, account_balance, currency: str,+) -> Optional[str]:+ balance = _decimal_or_none(account_balance)+ if balance is None:+ return None++ for line in credit_data.get("disaggregatedCreditLimits") or []:+ if not isinstance(line, dict):+ continue+ if str(line.get("consolidationType") or "").upper() != "CONSOLIDADO":+ continue+ if str(line.get("creditLineLimitType") or "").upper() != "LIMITE_CREDITO_TOTAL":+ continue+ used = _decimal_or_none(line.get("usedAmount"))+ if used is None or used != balance:+ continue++ limit = _decimal_or_none(line.get("customizedLimitAmount"))+ if limit is None:+ limit = _decimal_or_none(line.get("limitAmount"))+ if limit is None:+ continue+ identity = {+ "currency": currency,+ "line_name": str(line.get("lineName") or "").upper(),+ "limit": str(limit.normalize()),+ "used": str(used.normalize()),+ }+ encoded = json.dumps(identity, sort_keys=True, separators=(",", ":")).encode()+ return hashlib.sha256(encoded).hexdigest()+ return None++def _date_or_none(value) -> Optional[date]:if not value:return None@@ -203,6 +239,7 @@ def _build_account_data(acc: dict, type_mapper) -> AccountData:minimum_payment: Optional[Decimal] = Nonecard_brand: Optional[str] = Nonecard_level: Optional[str] = None+ shared_balance_group: Optional[str] = Noneif account_type == "credit_card" and credit_data:raw_limit = credit_data.get("creditLimit")@@ -215,6 +252,9 @@ def _build_account_data(acc: dict, type_mapper) -> AccountData:minimum_payment = Decimal(str(raw_min))card_brand = credit_data.get("brand") or Nonecard_level = credit_data.get("level") or None+ shared_balance_group = _consolidated_credit_balance_group(+ credit_data, acc.get("balance"), acc.get("currencyCode") or "USD"+ )return AccountData(external_id=acc["id"],@@ -231,6 +271,7 @@ def _build_account_data(acc: dict, type_mapper) -> AccountData:# Brazil has no IBAN; Pluggy's `number` is the branch/account number# (or the card number for credit cards), which serves the same purpose.masked_number=mask_last4(acc.get("number")),+ shared_balance_group=shared_balance_group,)diff --git a/backend/app/schemas/account.py b/backend/app/schemas/account.pyindex f0eec9d7..045e34a4 100644--- a/backend/app/schemas/account.py+++ b/backend/app/schemas/account.py@@ -67,6 +67,7 @@ class AccountRead(AccountBase):minimum_payment: Optional[float] = Nonecard_brand: Optional[str] = Nonecard_level: Optional[str] = None+ shared_balance_group: Optional[str] = Noneis_closed: bool = Falseclosed_at: Optional[datetime] = Nonediff --git a/backend/app/services/account_service.py b/backend/app/services/account_service.pyindex f8a6889a..c67ab560 100644--- a/backend/app/services/account_service.py+++ b/backend/app/services/account_service.py@@ -191,6 +191,7 @@ def serialize_account("minimum_payment": float(acc.minimum_payment) if acc.minimum_payment is not None else None,"card_brand": acc.card_brand,"card_level": acc.card_level,+ "shared_balance_group": acc.shared_balance_group,"institution_name": institution_name,"institution_logo_url": institution_logo_url,"available_credit": None,diff --git a/backend/app/services/connection_service.py b/backend/app/services/connection_service.pyindex 41ff26bc..9263e635 100644--- a/backend/app/services/connection_service.py+++ b/backend/app/services/connection_service.py@@ -1116,6 +1116,10 @@ async def handle_oauth_callback(minimum_payment=acc_data.minimum_payment if is_cc else None,card_brand=acc_data.card_brand if is_cc else None,card_level=acc_data.card_level if is_cc else None,+ shared_balance_group=(+ f"{connection.id}:{acc_data.shared_balance_group}"+ if acc_data.shared_balance_group else None+ ),institution_id=institution.id if institution else None,)session.add(account)@@ -1848,6 +1852,10 @@ async def sync_connection(account.card_brand = acc_data.card_brandif acc_data.card_level is not None:account.card_level = acc_data.card_level+ account.shared_balance_group = (+ f"{connection.id}:{acc_data.shared_balance_group}"+ if acc_data.shared_balance_group else None+ )else:is_cc = acc_data.type == "credit_card"account = Account(@@ -1865,6 +1873,10 @@ async def sync_connection(minimum_payment=acc_data.minimum_payment if is_cc else None,card_brand=acc_data.card_brand if is_cc else None,card_level=acc_data.card_level if is_cc else None,+ shared_balance_group=(+ f"{connection.id}:{acc_data.shared_balance_group}"+ if acc_data.shared_balance_group else None+ ),institution_id=institution.id if institution else None,)session.add(account)diff --git a/backend/app/services/dashboard_service.py b/backend/app/services/dashboard_service.pyindex a2167ecf..dcc6eb8f 100644--- a/backend/app/services/dashboard_service.py+++ b/backend/app/services/dashboard_service.py@@ -1412,6 +1412,7 @@ async def _total_balance_by_currency()totals: dict[str, float] = {}+ balances: dict[uuid.UUID, float] = {}for account in accounts:if account.connection_id:bal = float(account.balance)@@ -1423,7 +1424,24 @@ async def _total_balance_by_currency(bal -= connected_pending.get(account.id, 0.0)else:bal = manual_sums.get(account.id, 0.0)- totals[account.currency] = totals.get(account.currency, 0) + bal+ balances[account.id] = bal++ grouped: dict[str, list[Account]] = {}+ for account in accounts:+ key = account.shared_balance_group or str(account.id)+ grouped.setdefault(key, []).append(account)++ for group in grouped.values():+ total = sum(balances[account.id] for account in group)+ if len(group) > 1 and group[0].shared_balance_group:+ # Every card in the group carries the same shared debt, so `total`+ # counts it len(group) times; strip the duplicates.+ current_shared = await _account_balance_at(+ session, group[0], today, include_pending=include_pending+ )+ total -= current_shared * (len(group) - 1)+ currency = group[0].currency+ totals[currency] = totals.get(currency, 0) + totalreturn totalsdiff --git a/backend/tests/test_dashboard_service.py b/backend/tests/test_dashboard_service.pyindex af738fc5..97969922 100644--- a/backend/tests/test_dashboard_service.py+++ b/backend/tests/test_dashboard_service.py@@ -305,6 +305,57 @@ async def test_total_balance_by_currency(session: AsyncSession, test_user, test_assert totals.get("USD", 0) == pytest.approx(500.0)+async def test_total_balance_counts_shared_credit_balance_once(+ session, test_user, test_workspace, test_connection,+):+ group = "pluggy:connection:shared-credit"+ first = await _make_account(+ session, test_user.id, "Shared Visa", acc_type="credit_card", balance="300.00",+ connection_id=test_connection.id,+ )+ second = await _make_account(+ session, test_user.id, "Shared Mastercard", acc_type="credit_card", balance="300.00",+ connection_id=test_connection.id,+ )+ first.workspace_id = test_workspace.id+ second.workspace_id = test_workspace.id+ first.shared_balance_group = group+ second.shared_balance_group = group+ await session.commit()++ totals = await _total_balance_by_currency(session, test_workspace.id, date.today())++ assert totals["BRL"] == pytest.approx(-300.0)+++async def test_total_balance_backtracks_shared_credit_balance_across_all_cards(+ session, test_user, test_workspace, test_connection,+):+ group = "pluggy:connection:shared-credit"+ first = await _make_account(+ session, test_user.id, "Shared Visa", acc_type="credit_card", balance="300.00",+ connection_id=test_connection.id,+ )+ second = await _make_account(+ session, test_user.id, "Shared Mastercard", acc_type="credit_card", balance="300.00",+ connection_id=test_connection.id,+ )+ for account in (first, second):+ account.workspace_id = test_workspace.id+ account.shared_balance_group = group+ await session.commit()+ await _add_txn(session, test_user.id, first.id, 50, "debit", date.today())+ await _add_txn(session, test_user.id, second.id, 25, "debit", date.today())++ totals = await _total_balance_by_currency(+ session, test_workspace.id, date.today() - timedelta(days=1)+ )++ assert totals["BRL"] == pytest.approx(-225.0)++# ---------------------------------------------------------------------------# get_summary# ---------------------------------------------------------------------------diff --git a/backend/tests/test_providers_pluggy.py b/backend/tests/test_providers_pluggy.pyindex 5f6b53dc..a69e5963 100644--- a/backend/tests/test_providers_pluggy.py+++ b/backend/tests/test_providers_pluggy.py@@ -374,6 +374,51 @@ def test_build_account_data_without_number_leaves_mask_none():assert out.masked_number is None+def test_build_account_data_groups_consolidated_credit_line():+ from app.providers.pluggy import _build_account_data++ credit_data = {+ "disaggregatedCreditLimits": [{+ "lineName": "CREDITO_A_VISTA",+ "creditLineLimitType": "LIMITE_CREDITO_TOTAL",+ "consolidationType": "CONSOLIDADO",+ "usedAmount": 250.50,+ "customizedLimitAmount": 1000,+ }]+ }+ visa = _build_account_data(+ {"id": "visa", "name": "Visa", "type": "CREDIT", "balance": 250.50,+ "currencyCode": "BRL", "creditData": credit_data},+ PluggyProvider._map_account_type,+ )+ mastercard = _build_account_data(+ {"id": "mc", "name": "Mastercard", "type": "CREDIT", "balance": 250.50,+ "currencyCode": "BRL", "creditData": credit_data},+ PluggyProvider._map_account_type,+ )++ assert visa.shared_balance_group is not None+ assert visa.shared_balance_group == mastercard.shared_balance_group+++def test_build_account_data_does_not_group_individual_credit_line():+ from app.providers.pluggy import _build_account_data++ acc = _build_account_data(+ {"id": "visa", "name": "Visa", "type": "CREDIT", "balance": 250,+ "currencyCode": "BRL", "creditData": {"disaggregatedCreditLimits": [{+ "lineName": "CREDITO_A_VISTA",+ "creditLineLimitType": "LIMITE_CREDITO_TOTAL",+ "consolidationType": "INDIVIDUAL",+ "usedAmount": 250,+ "limitAmount": 1000,+ }]}},+ PluggyProvider._map_account_type,+ )++ assert acc.shared_balance_group is None++def test_build_account_data_maps_bank_savings_subtype_to_savings():from app.providers.pluggy import _build_account_datadiff --git a/frontend/src/components/app-layout.tsx b/frontend/src/components/app-layout.tsxindex b3b07d45..ea3ec7fd 100644--- a/frontend/src/components/app-layout.tsx+++ b/frontend/src/components/app-layout.tsx@@ -189,7 +189,12 @@ export function AppLayout() {const visibleAccounts = activeAccountIds? allAccounts.filter((a) => activeAccountIds.includes(a.id)): allAccounts+ const sharedBalanceGroups = new Set<string>()const totalBalance = visibleAccounts.reduce((sum, a) => {+ if (a.shared_balance_group) {+ if (sharedBalanceGroups.has(a.shared_balance_group)) return sum+ sharedBalanceGroups.add(a.shared_balance_group)+ }return sum + Number(a.balance_primary ?? a.current_balance)}, 0)const versionA11yLabel = t('app.versionAriaLabel', { version: APP_VERSION })@@ -455,6 +460,7 @@ export function AppLayout() {<span className="block truncate font-medium">{getAccountName(acc)}</span><span className="block text-[10px] text-sidebar-muted/60">{t(`accounts.type${typeKey}`)}+ {acc.shared_balance_group && ` · ${t('accounts.sharedCreditBalance')}`}</span></div><div className="text-right shrink-0 ml-2">diff --git a/frontend/src/locales/de.json b/frontend/src/locales/de.jsonindex a52405f1..ea076bdb 100644--- a/frontend/src/locales/de.json+++ b/frontend/src/locales/de.json@@ -890,6 +890,7 @@"expenses": "Ausgaben","projectedBalance": "Prognostizierter Saldo","notSettled": "Nicht abgerechnet",+ "sharedCreditBalance": "Geteilte Kreditlinie","projectedIncome": "Prognostizierte Einnahmen","projectedExpenses": "Prognostizierte Ausgaben","thisMonth": "Diesen Monat",diff --git a/frontend/src/locales/el.json b/frontend/src/locales/el.jsonindex 12adce1c..88700ec0 100644--- a/frontend/src/locales/el.json+++ b/frontend/src/locales/el.json@@ -624,6 +624,7 @@"expenses": "Έξοδα","projectedBalance": "Προβλεπόμενο υπόλοιπο","notSettled": "Μη εξοφλημένο",+ "sharedCreditBalance": "Κοινή πιστωτική γραμμή","projectedIncome": "Προβλεπόμενα έσοδα","projectedExpenses": "Προβλεπόμενα έξοδα","thisMonth": "Αυτόν τον μήνα",diff --git a/frontend/src/locales/en.json b/frontend/src/locales/en.jsonindex c753b995..a3f6135d 100644--- a/frontend/src/locales/en.json+++ b/frontend/src/locales/en.json@@ -889,6 +889,7 @@"expenses": "Expenses","projectedBalance": "Projected Balance","notSettled": "Not settled",+ "sharedCreditBalance": "Shared credit line","projectedIncome": "Projected Income","projectedExpenses": "Projected Expenses","thisMonth": "This month",diff --git a/frontend/src/locales/es.json b/frontend/src/locales/es.jsonindex 3366cbab..cbba80d4 100644--- a/frontend/src/locales/es.json+++ b/frontend/src/locales/es.json@@ -890,6 +890,7 @@"expenses": "Gastos","projectedBalance": "Saldo proyectado","notSettled": "Sin liquidar",+ "sharedCreditBalance": "Línea de crédito compartida","projectedIncome": "Ingresos proyectados","projectedExpenses": "Gastos proyectados","thisMonth": "Este mes",diff --git a/frontend/src/locales/fr.json b/frontend/src/locales/fr.jsonindex 71abb747..6c633c76 100644--- a/frontend/src/locales/fr.json+++ b/frontend/src/locales/fr.json@@ -890,6 +890,7 @@"expenses": "Dépenses","projectedBalance": "Solde projeté","notSettled": "Non réglé",+ "sharedCreditBalance": "Ligne de crédit partagée","projectedIncome": "Revenus projetés","projectedExpenses": "Dépenses projetées","thisMonth": "Ce mois-ci",diff --git a/frontend/src/locales/hi.json b/frontend/src/locales/hi.jsonindex dfade35b..fbb1f9fa 100644--- a/frontend/src/locales/hi.json+++ b/frontend/src/locales/hi.json@@ -889,6 +889,7 @@"expenses": "खर्च","projectedBalance": "अनुमानित शेष राशि","notSettled": "निपटा नहीं",+ "sharedCreditBalance": "साझा क्रेडिट लाइन","projectedIncome": "अनुमानित आय","projectedExpenses": "अनुमानित खर्च","thisMonth": "इस महीने",diff --git a/frontend/src/locales/it.json b/frontend/src/locales/it.jsonindex fcbfd553..0f7b4d73 100644--- a/frontend/src/locales/it.json+++ b/frontend/src/locales/it.json@@ -890,6 +890,7 @@"expenses": "Spese","projectedBalance": "Saldo previsto","notSettled": "Non liquidato",+ "sharedCreditBalance": "Linea di credito condivisa","projectedIncome": "Entrate previste","projectedExpenses": "Spese previste","thisMonth": "Questo mese",diff --git a/frontend/src/locales/ja.json b/frontend/src/locales/ja.jsonindex 3f2788b2..f8d1c6dd 100644--- a/frontend/src/locales/ja.json+++ b/frontend/src/locales/ja.json@@ -889,6 +889,7 @@"expenses": "支出","projectedBalance": "予測残高","notSettled": "未決済",+ "sharedCreditBalance": "共有クレジットライン","projectedIncome": "予測収入","projectedExpenses": "予測支出","thisMonth": "今月",diff --git a/frontend/src/locales/nl.json b/frontend/src/locales/nl.jsonindex 209d022a..5e5c8957 100644--- a/frontend/src/locales/nl.json+++ b/frontend/src/locales/nl.json@@ -890,6 +890,7 @@"expenses": "Kosten","projectedBalance": "Geprojecteerd saldo","notSettled": "Niet geregeld",+ "sharedCreditBalance": "Gedeelde kredietlijn","projectedIncome": "Geprojecteerd inkomen","projectedExpenses": "Geprojecteerde uitgaven","thisMonth": "Deze maand",diff --git a/frontend/src/locales/pl.json b/frontend/src/locales/pl.jsonindex b2a13109..a06bb2ad 100644--- a/frontend/src/locales/pl.json+++ b/frontend/src/locales/pl.json@@ -935,6 +935,7 @@"expenses": "Wydatki","projectedBalance": "Saldo prognozowane","notSettled": "Nierozliczone",+ "sharedCreditBalance": "Wspólna linia kredytowa","projectedIncome": "Prognozowane przychody","projectedExpenses": "Prognozowane wydatki","thisMonth": "Bieżący miesiąc",diff --git a/frontend/src/locales/pt-BR.json b/frontend/src/locales/pt-BR.jsonindex 14058b8c..9eec4e0c 100644--- a/frontend/src/locales/pt-BR.json+++ b/frontend/src/locales/pt-BR.json@@ -890,6 +890,7 @@"expenses": "Saídas","projectedBalance": "Saldo projetado","notSettled": "Não liquidado",+ "sharedCreditBalance": "Linha de crédito compartilhada","projectedIncome": "Entradas previstas","projectedExpenses": "Saídas previstas","thisMonth": "Este mês",diff --git a/frontend/src/locales/pt-PT.json b/frontend/src/locales/pt-PT.jsonindex 2f0d9ead..373bb10b 100644--- a/frontend/src/locales/pt-PT.json+++ b/frontend/src/locales/pt-PT.json@@ -890,6 +890,7 @@"expenses": "Saídas","projectedBalance": "Saldo projetado","notSettled": "Não liquidado",+ "sharedCreditBalance": "Linha de crédito partilhada","projectedIncome": "Entradas previstas","projectedExpenses": "Saídas previstas","thisMonth": "Este mês",diff --git a/frontend/src/locales/ru.json b/frontend/src/locales/ru.jsonindex f6683fc3..aa27d78c 100644--- a/frontend/src/locales/ru.json+++ b/frontend/src/locales/ru.json@@ -902,6 +902,7 @@"expenses": "Расходы","projectedBalance": "Прогнозируемый баланс","notSettled": "Не проведено",+ "sharedCreditBalance": "Общий кредитный лимит","projectedIncome": "Прогнозируемый доход","projectedExpenses": "Прогнозируемые расходы","thisMonth": "Этот месяц",diff --git a/frontend/src/locales/sk.json b/frontend/src/locales/sk.jsonindex 35bd18e9..4d3bff97 100644--- a/frontend/src/locales/sk.json+++ b/frontend/src/locales/sk.json@@ -949,6 +949,7 @@"expenses": "Výdavky","projectedBalance": "Predpokladaný zostatok","notSettled": "Nezaúčtované",+ "sharedCreditBalance": "Zdieľaný úverový rámec","projectedIncome": "Predpokladané príjmy","projectedExpenses": "Predpokladané výdavky","thisMonth": "Tento mesiac",diff --git a/frontend/src/locales/uk.json b/frontend/src/locales/uk.jsonindex e49164e6..beb9f125 100644--- a/frontend/src/locales/uk.json+++ b/frontend/src/locales/uk.json@@ -902,6 +902,7 @@"expenses": "Витрати","projectedBalance": "Прогнозований баланс","notSettled": "Не проведено",+ "sharedCreditBalance": "Спільна кредитна лінія","projectedIncome": "Прогнозований дохід","projectedExpenses": "Прогнозовані витрати","thisMonth": "Цей місяць",diff --git a/frontend/src/pages/accounts.tsx b/frontend/src/pages/accounts.tsxindex b36a0d44..5d6a8cce 100644--- a/frontend/src/pages/accounts.tsx+++ b/frontend/src/pages/accounts.tsx@@ -270,6 +270,7 @@ export default function AccountsPage() {<p className="text-xs text-muted-foreground">{t(cfg.label)}{accountMask && <> · <span className="tabular-nums">{accountMask}</span></>}+ {acc.shared_balance_group && <> · <span>{t('accounts.sharedCreditBalance')}</span></>}{dueText && <> · <span className={dueClass}>{dueText}</span></>}</p></div>@@ -417,6 +418,7 @@ export default function AccountsPage() {<p className="text-xs text-muted-foreground">{t(cfg.label)}{accountMask && <> · <span className="tabular-nums">{accountMask}</span></>}+ {acc.shared_balance_group && <> · <span>{t('accounts.sharedCreditBalance')}</span></>}{dueText && <> · <span className={dueClass}>{dueText}</span></>}</p></div>diff --git a/frontend/src/types/index.ts b/frontend/src/types/index.tsindex 1685e9f1..893ca4a9 100644--- a/frontend/src/types/index.ts+++ b/frontend/src/types/index.ts@@ -174,6 +174,7 @@ export interface Account {minimum_payment: number | nullcard_brand: string | nullcard_level: string | null+ shared_balance_group: string | nullis_closed: booleanclosed_at: string | null}