Open-source personal finance manager. Self-hosted, privacy-first.
fix(simplefin): normalize credit-card balance sign so connected cards don't double-count (#351)
Albert Dolkunbb276300f96d
diff --git a/backend/app/services/account_service.py b/backend/app/services/account_service.pyindex 87132a9a..face8210 100644--- a/backend/app/services/account_service.py+++ b/backend/app/services/account_service.py@@ -21,6 +21,21 @@ def get_account_name(account: Account) -> str:return account.display_name or account.name+def _simplefin_to_internal_balance(provider: str, account_type: str, balance: Decimal) -> Decimal:+ """Normalize a SimpleFIN balance to Securo's positive-for-debt convention.++ SimpleFIN reports a credit card's balance as negative debt and exposes no+ account type, so the provider stores it raw and labels every account+ "checking". Pluggy/Enable report card debt as a positive number, which is+ the convention every downstream site (serialize_account, _account_balance_at,+ sync_opening_balance_for_connected_account, ...) assumes. Flip SimpleFIN card+ balances to match so those sites stay provider-agnostic.+ """+ if provider == "simplefin" and account_type == "credit_card":+ return -balance+ return balance++async def get_accounts(session: AsyncSession, workspace_id: uuid.UUID, include_closed: bool = False) -> list[dict]:# Subquery: compute current_balance per account from transactions in one pass# Use amount_primary only when tx currency differs from account currency@@ -288,6 +303,7 @@ async def update_account(disallowed = set(update_data.keys()) - editable_fieldsif disallowed:raise ValueError("Cannot edit bank-connected accounts")+ old_type = account.typenew_type = update_data.get("type", account.type)cc_fields = editable_fields - {"display_name", "type"}cc_update = {k: v for k, v in update_data.items() if k in cc_fields}@@ -295,6 +311,22 @@ async def update_account(raise ValueError("Credit card fields can only be set on credit card accounts")for key, value in update_data.items():setattr(account, key, value)+ # SimpleFIN stores a card's balance with the raw provider sign (negative+ # for debt) under type="checking". When the user flips the type across+ # the credit_card boundary, the downstream display sites start (or stop)+ # applying the positive-for-debt negation, so the stored value must flip+ # too — otherwise the card double-counts. Mirror the ingestion-time+ # normalization (_simplefin_to_internal_balance) here so the correction+ # is immediate, not deferred to the next sync. Load the provider via+ # session.get (identity-map hit, never a lazy-load that throws).+ if old_type != new_type and "credit_card" in (old_type, new_type):+ conn = (+ await session.get(BankConnection, account.connection_id)+ if account.connection_id is not None+ else None+ )+ if conn is not None and conn.provider == "simplefin":+ account.balance = -account.balance# If the override moves the account away from credit_card, drop any# stale card metadata so it isn't left half credit-card.if new_type != "credit_card":diff --git a/backend/app/services/connection_service.py b/backend/app/services/connection_service.pyindex d738f70f..d7a82801 100644--- a/backend/app/services/connection_service.py+++ b/backend/app/services/connection_service.py@@ -28,7 +28,10 @@ from app.providers.base import ()from app.services import oauth_statefrom app.services import admin_service-from app.services.account_service import sync_opening_balance_for_connected_account+from app.services.account_service import (+ _simplefin_to_internal_balance,+ sync_opening_balance_for_connected_account,+)from app.services.asset_group_service import ensure_group_for_connectionfrom app.services.credit_card_service import apply_effective_datefrom app.services.rule_service import apply_rules_to_transaction@@ -1166,7 +1169,15 @@ async def sync_connection(continueif account:- account.balance = acc_data.balance+ # Normalize the provider sign using the account's CURRENT type,+ # which reflects any user override (sync never rewrites `type`).+ # SimpleFIN reports card debt as negative under a "checking"+ # label; once the user overrides the type to credit_card the+ # downstream sites negate it, so store positive-for-debt to keep+ # them provider-agnostic and avoid double-counting.+ account.balance = _simplefin_to_internal_balance(+ connection.provider, account.type, acc_data.balance+ )account.name = acc_data.nameif acc_data.type == "credit_card":# Preserve existing CC metadata when the provider doesn'tdiff --git a/backend/tests/test_account_service.py b/backend/tests/test_account_service.pyindex 015f1a17..46589142 100644--- a/backend/tests/test_account_service.py+++ b/backend/tests/test_account_service.py@@ -23,6 +23,7 @@ from app.models.recurring_transaction import RecurringTransactionfrom app.models.transaction import Transactionfrom app.schemas.account import AccountCreate, AccountUpdatefrom app.services.account_service import (+ _simplefin_to_internal_balance,create_account,close_account,delete_account,@@ -31,6 +32,7 @@ from app.services.account_service import (get_account_summary,get_accounts,reopen_account,+ serialize_account,update_account,)@@ -769,3 +771,141 @@ async def test_get_account_balance_history_credit_card_negated(# CC with connection_id has sign=-1.0: a debit (spending) on CC# produces negative balance, negated to positive (showing debt increase)assert history[0]["balance"] == pytest.approx(500.0)+++# ---------------------------------------------------------------------------+# SimpleFIN credit-card balance-sign normalization+# ---------------------------------------------------------------------------+++async def _make_provider_connection(+ session: AsyncSession, user_id: uuid.UUID, provider: str,+) -> "uuid.UUID":+ from datetime import datetime, timezone+ from app.models.bank_connection import BankConnection+ conn = BankConnection(+ id=uuid.uuid4(), user_id=user_id, provider=provider,+ external_id=f"ext-{provider}-{uuid.uuid4().hex[:8]}",+ institution_name=f"{provider} bank", credentials={"token": "fake"},+ status="active", last_sync_at=datetime.now(timezone.utc),+ created_at=datetime.now(timezone.utc),+ )+ session.add(conn)+ await session.commit()+ await session.refresh(conn)+ return conn.id+++def test_simplefin_to_internal_balance_flips_card():+ """SimpleFIN reports card debt as a negative number; normalize to positive."""+ assert _simplefin_to_internal_balance(+ "simplefin", "credit_card", Decimal("-500.00")+ ) == Decimal("500.00")+++def test_simplefin_to_internal_balance_checking_unchanged():+ """A SimpleFIN non-card balance is already in the right convention."""+ assert _simplefin_to_internal_balance(+ "simplefin", "checking", Decimal("1500.00")+ ) == Decimal("1500.00")+++def test_simplefin_to_internal_balance_other_provider_unchanged():+ """Pluggy/Enable already use positive-for-debt — never flip their cards."""+ assert _simplefin_to_internal_balance(+ "pluggy", "credit_card", Decimal("500.00")+ ) == Decimal("500.00")+ assert _simplefin_to_internal_balance(+ "enable_banking", "credit_card", Decimal("500.00")+ ) == Decimal("500.00")+++async def test_update_simplefin_account_to_credit_card_flips_balance(+ session: AsyncSession, test_user, test_workspace,+):+ """Decisive case: a SimpleFIN account stores debt as a negative balance under+ type="checking". When the user overrides the type to credit_card, the stored+ balance must flip to positive-for-debt so the downstream negation in+ serialize_account / dashboard yields -500 (owed) instead of +500 — without+ the flip the card double-counts in net worth (≈2x the debt)."""+ conn_id = await _make_provider_connection(session, test_user.id, "simplefin")+ account = await _make_account(+ session, test_user.id, "SimpleFIN Card", acc_type="checking",+ balance="-500.00", connection_id=conn_id, external_id="sf-card-1",+ )++ updated = await update_account(+ session, account.id, test_workspace.id, AccountUpdate(type="credit_card")+ )+ assert updated is not None+ assert updated.type == "credit_card"+ # Stored balance flips to positive-for-debt (matches Pluggy/Enable).+ assert updated.balance == Decimal("500.00")+ # Resolved/serialized balance is negative = the user owes 500.+ payload = serialize_account(updated, None, None)+ assert payload["current_balance"] == pytest.approx(-500.0)+++async def test_update_simplefin_account_away_from_credit_card_flips_back(+ session: AsyncSession, test_user, test_workspace,+):+ """Reverse direction: moving a SimpleFIN card back to a non-card type must+ flip the stored balance back to the raw provider sign so it stays+ consistent with a fresh sync (which writes the raw negative value)."""+ conn_id = await _make_provider_connection(session, test_user.id, "simplefin")+ account = await _make_account(+ session, test_user.id, "SimpleFIN WasCard", acc_type="credit_card",+ balance="500.00", connection_id=conn_id, external_id="sf-card-2",+ )++ updated = await update_account(+ session, account.id, test_workspace.id, AccountUpdate(type="checking")+ )+ assert updated is not None+ assert updated.type == "checking"+ assert updated.balance == Decimal("-500.00")+++async def test_update_pluggy_account_to_credit_card_does_not_flip(+ session: AsyncSession, test_user, test_workspace,+):+ """No double-count for non-SimpleFIN providers: a Pluggy account already+ uses positive-for-debt, so a type edit must NOT touch the stored balance."""+ conn_id = await _make_provider_connection(session, test_user.id, "pluggy")+ account = await _make_account(+ session, test_user.id, "Pluggy Card", acc_type="checking",+ balance="500.00", connection_id=conn_id, external_id="pl-card-1",+ )++ updated = await update_account(+ session, account.id, test_workspace.id, AccountUpdate(type="credit_card")+ )+ assert updated is not None+ assert updated.type == "credit_card"+ # Untouched — Pluggy was already positive-for-debt.+ assert updated.balance == Decimal("500.00")+ payload = serialize_account(updated, None, None)+ assert payload["current_balance"] == pytest.approx(-500.0)+++async def test_update_simplefin_type_change_not_crossing_card_keeps_balance(+ session: AsyncSession, test_user, test_workspace,+):+ """A SimpleFIN type edit that doesn't cross the credit_card boundary (e.g.+ checking → savings) must leave the stored balance alone."""+ conn_id = await _make_provider_connection(session, test_user.id, "simplefin")+ account = await _make_account(+ session, test_user.id, "SimpleFIN Savings", acc_type="checking",+ balance="1500.00", connection_id=conn_id, external_id="sf-sav-1",+ )++ updated = await update_account(+ session, account.id, test_workspace.id, AccountUpdate(type="savings")+ )+ assert updated is not None+ assert updated.type == "savings"+ assert updated.balance == Decimal("1500.00")diff --git a/backend/tests/test_connection_service.py b/backend/tests/test_connection_service.pyindex 5b646ca3..01830c25 100644--- a/backend/tests/test_connection_service.py+++ b/backend/tests/test_connection_service.py@@ -1979,3 +1979,111 @@ async def test_sync_keeps_genuine_same_day_repeats())).scalars().all()assert len(rows) == 2, "identical-description same-day repeats must be kept"+++# ---------------------------------------------------------------------------+# SimpleFIN credit-card balance-sign normalization on sync (UPDATE branch)+# ---------------------------------------------------------------------------+++async def _make_simplefin_connection(+ session: AsyncSession, user_id: uuid.UUID, name: str = "SimpleFIN Bank",+) -> BankConnection:+ conn = BankConnection(+ id=uuid.uuid4(), user_id=user_id, provider="simplefin",+ external_id=f"ext-sf-{uuid.uuid4().hex[:8]}",+ institution_name=name, credentials={"token": "fake"},+ status="active", last_sync_at=datetime.now(timezone.utc),+ created_at=datetime.now(timezone.utc),+ )+ session.add(conn)+ await session.commit()+ await session.refresh(conn)+ return conn+++async def test_sync_normalizes_simplefin_card_balance_to_positive_for_debt(+ session: AsyncSession, test_user, test_workspace,+):+ """SimpleFIN reports a card's debt as a NEGATIVE balance under a "checking"+ label. Once the user has overridden the account type to credit_card, a+ re-sync must store the balance positive-for-debt (Pluggy/Enable convention)+ so the downstream negation yields the right sign instead of double-counting.+ The UPDATE branch keys the normalization off the account's CURRENT type,+ which carries the user override (sync never rewrites `type`)."""+ from app.models.account import Account++ conn = await _make_simplefin_connection(session, test_user.id)+ # Pre-existing account the user already flipped to credit_card. Stored+ # balance is already positive-for-debt from the prior edit.+ account = Account(+ id=uuid.uuid4(), user_id=test_user.id, connection_id=conn.id,+ external_id="sf-cc-1", name="SimpleFIN Card", type="credit_card",+ balance=Decimal("500.00"), currency="USD",+ )+ session.add(account)+ await session.commit()++ mock_provider = AsyncMock()+ mock_provider.refresh_credentials = AsyncMock(return_value={"token": "t"})+ # SimpleFIN provider parses every account as type="checking" and reports+ # the raw negative debt balance.+ mock_provider.get_accounts = AsyncMock(return_value=[+ AccountData(+ external_id="sf-cc-1", name="SimpleFIN Card",+ type="checking", balance=Decimal("-650.00"), currency="USD",+ ),+ ])+ mock_provider.get_transactions = AsyncMock(return_value=[])+ mock_provider.get_bills = AsyncMock(return_value=[])++ with patch("app.services.connection_service.get_provider", return_value=mock_provider), \+ patch("app.services.connection_service.detect_transfer_pairs", new_callable=AsyncMock), \+ patch("app.services.connection_service.stamp_primary_amount", new_callable=AsyncMock), \+ patch("app.services.connection_service.apply_rules_to_transaction", new_callable=AsyncMock):+ await sync_connection(session, conn.id, test_workspace.id, test_user.id)++ await session.refresh(account)+ # Incoming -650 (raw SimpleFIN) → stored +650 (positive-for-debt). The user+ # override (type=credit_card) is preserved.+ assert account.type == "credit_card"+ assert account.balance == Decimal("650.00")+++async def test_sync_leaves_simplefin_checking_balance_unchanged(+ session: AsyncSession, test_user, test_workspace,+):+ """A SimpleFIN non-card account (no override) keeps the provider's balance+ verbatim — the normalization only applies to credit_card."""+ from app.models.account import Account++ conn = await _make_simplefin_connection(session, test_user.id, "SF Checking")+ account = Account(+ id=uuid.uuid4(), user_id=test_user.id, connection_id=conn.id,+ external_id="sf-chk-1", name="SimpleFIN Checking", type="checking",+ balance=Decimal("0.00"), currency="USD",+ )+ session.add(account)+ await session.commit()++ mock_provider = AsyncMock()+ mock_provider.refresh_credentials = AsyncMock(return_value={"token": "t"})+ mock_provider.get_accounts = AsyncMock(return_value=[+ AccountData(+ external_id="sf-chk-1", name="SimpleFIN Checking",+ type="checking", balance=Decimal("1234.56"), currency="USD",+ ),+ ])+ mock_provider.get_transactions = AsyncMock(return_value=[])+ mock_provider.get_bills = AsyncMock(return_value=[])++ with patch("app.services.connection_service.get_provider", return_value=mock_provider), \+ patch("app.services.connection_service.detect_transfer_pairs", new_callable=AsyncMock), \+ patch("app.services.connection_service.stamp_primary_amount", new_callable=AsyncMock), \+ patch("app.services.connection_service.apply_rules_to_transaction", new_callable=AsyncMock):+ await sync_connection(session, conn.id, test_workspace.id, test_user.id)++ await session.refresh(account)+ assert account.balance == Decimal("1234.56")