Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

16.1 KB
Raw Blame
from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from datetime import date
from decimal import Decimal
from typing import Literal, Optional


# Outcome of asking a provider to pull fresh data from the underlying institution
# before we read accounts/transactions.
#
# - "refreshed":         provider successfully synced; safe to read.
# - "skipped":           provider has no on-demand refresh (default for most providers).
# - "needs_user_action": provider needs the user to act (MFA, expired credentials).
#                        Caller should mark the connection as needing reconnection
#                        and skip the read pass.
# - "failed":            transient error (timeout, rate limit). Caller may proceed
#                        with a stale read; we don't punish the user for it.
RefreshOutcome = Literal["refreshed", "skipped", "needs_user_action", "failed"]


def default_oauth_redirect_uri() -> str:
    """The OAuth callback URL implied by where the frontend is served.

    Providers fall back to this when their own ``*_OAUTH_REDIRECT_URI`` is
    unset, so a deployment on a custom port or domain works without setting one
    variable per provider. Deriving it here rather than in Compose also keeps
    the compose files free of nested ``${VAR:-${OTHER:-x}}`` interpolation,
    which podman-compose cannot parse (containers/podman-compose#1064).
    """
    from app.core.config import get_settings

    return f"{get_settings().frontend_url.rstrip('/')}/oauth/callback"


def mask_last4(value: Optional[str]) -> Optional[str]:
    """Reduce a bank-assigned account identifier to its last four characters.

    Providers expose different identifiers for the same purpose: an IBAN
    (Enable Banking), a branch/account number (Pluggy), a card number. They all
    serve one job here, telling two same-named accounts apart, so we normalize
    them to a single shape and deliberately keep only the tail. Storing the full
    identifier would put a payable bank reference in the database for no gain.

    Separators (spaces, dashes) are stripped first, since IBANs are commonly
    formatted in groups of four. Returns None when the source is missing or too
    short to mask, so callers never render a partial identifier.
    """
    if not value:
        return None
    cleaned = "".join(ch for ch in str(value) if ch.isalnum())
    if len(cleaned) < 4:
        return None
    return cleaned[-4:]


@dataclass
class AccountData:
    # The provider's identifier for this account. It is expected to be stable
    # across re-syncs, and the sync matches an incoming account on it first. A
    # provider that re-keys it (Enable Banking mints a `uid` scoped to a single
    # session) must also set `stable_external_id`, or re-syncing inserts a
    # duplicate instead of recognising the account it already imported.
    external_id: str
    name: str
    type: str  # checking, savings, credit_card
    balance: Decimal
    currency: str
    credit_limit: Optional[Decimal] = None
    statement_close_day: Optional[int] = None
    payment_due_day: Optional[int] = None
    minimum_payment: Optional[Decimal] = None
    card_brand: Optional[str] = None
    card_level: Optional[str] = None
    # Last 4 chars of the bank's own identifier for the account, when the
    # 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
    # The provider's session-independent identifier for this account, when it
    # offers one. See `external_id` above: it is *supposed* to be stable, and
    # Enable Banking is the provider that breaks that. This is the value that
    # survives (EB's `identification_hash`), and the sync uses it to rebind the
    # existing row to the new uid instead of duplicating the account.
    stable_external_id: 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 of
    # minting a new one; name-only hints fall back to name identity.
    institution_external_id: Optional[str] = None
    institution_name: Optional[str] = None
    institution_logo_url: Optional[str] = None
    # Part of `balance` that the bank has auto-applied to an investment which
    # the provider also reports as a holding (Pluggy
    # `bankData.automaticallyInvestedBalance`, issue #843). Zero when unknown.
    # The sync subtracts it only when a live holding is counted for this
    # account (see connection_service._auto_invested_deductions), so the
    # money is counted once: as the asset when one mirrors it, as cash
    # otherwise.
    auto_invested_balance: Decimal = Decimal(0)


@dataclass
class TransactionData:
    external_id: str
    description: str
    amount: Decimal
    date: date
    type: str  # debit, credit
    currency: Optional[str] = None  # ISO currency code (e.g. BRL, USD)
    amount_in_account_currency: Optional[Decimal] = None  # Bank-provided conversion for intl txns
    pluggy_category: Optional[str] = None
    status: str = "posted"  # posted, pending
    payee: Optional[str] = None
    raw_data: Optional[dict] = None
    # Installment metadata (parcelamento) — populated by CC providers that expose it.
    installment_number: Optional[int] = None
    total_installments: Optional[int] = None
    installment_total_amount: Optional[Decimal] = None
    installment_purchase_date: Optional[date] = None
    # Provider-side identifier of the bill this transaction belongs to.
    # Resolved to a credit_card_bills.id FK at sync time (issue #92).
    bill_external_id: Optional[str] = None


@dataclass
class ConnectionData:
    external_id: str
    institution_name: str
    credentials: dict
    accounts: list[AccountData]
    # Fully-formed institution logo URL when the provider exposes one
    # (Pluggy connector.imageUrl, Enable Banking ASPSP logo). None for
    # providers/institutions without a logo (e.g. SimpleFin).
    logo_url: Optional[str] = None


@dataclass
class ConnectTokenData:
    access_token: str


@dataclass
class BillData:
    """A normalized credit-card bill (fatura), provider-agnostic.

    Only the fields universal to a credit-card statement are promoted. Anything
    a specific integration provides on top (finance charges, recorded payments,
    installment options, etc.) is preserved verbatim in `raw_data` so we can
    pull more out later without forcing a schema-shaped opinion now.
    """

    external_id: str
    due_date: date
    total_amount: Decimal
    currency: str = "BRL"
    minimum_payment: Optional[Decimal] = None
    raw_data: Optional[dict] = None


@dataclass
class HoldingData:
    """A normalized investment holding, provider-agnostic.

    Providers that don't expose holdings-style data return an empty list
    from `get_holdings`. Provider-specific fields that don't fit the common
    shape (rate, profit, issuer, status, type/subtype labels, etc.) go in
    `metadata` as-is — the sync layer stores it on Asset.external_metadata
    without trying to normalize it.
    """

    external_id: str
    name: str
    currency: str
    current_value: Decimal
    quantity: Optional[Decimal] = None
    unit_price: Optional[Decimal] = None
    purchase_price: Optional[Decimal] = None
    purchase_date: Optional[date] = None
    isin: Optional[str] = None
    # Exchange/asset symbol (e.g. "AAPL", "DOGE") for the dedicated
    # `assets.ticker` column. Kept separate from `currency`: connectors that
    # report a crypto position put the ticker in both, and only one of them
    # belongs in a 3-char ISO currency field.
    ticker: Optional[str] = None
    maturity_date: Optional[date] = None
    is_withdrawn: bool = False  # provider signaled the position was sold/transferred
    metadata: Optional[dict] = None
    # Owning-account hint (SimpleFIN — issue #345): holdings are reported per
    # account, so each investment account gets its own wallet ("401(k)" apart
    # from "Rollover IRA"). None = the connection-default wallet, for
    # providers whose holdings aren't attributable to an account.
    account_external_id: Optional[str] = None
    account_name: Optional[str] = None


@dataclass
class InstitutionData:
    """One ASPSP/bank offered by an OAuth provider."""

    name: str  # canonical identifier the provider expects in subsequent calls
    display_name: str
    country: str  # ISO 3166-1 alpha-2
    logo: Optional[str] = None
    bic: Optional[str] = None
    psu_types: list[str] = field(default_factory=list)  # e.g. ["personal", "business"]
    max_consent_days: Optional[int] = None
    max_history_days: Optional[int] = None


@dataclass
class InstitutionListData:
    """List of supported institutions (banks) for a provider, optionally for one country."""

    countries: list[str]
    institutions: list[InstitutionData]


class SessionExpiredError(Exception):
    """Raised when a provider session/consent has expired and reauth is required."""


class ProviderUserActionRequired(Exception):
    """Raised when a provider needs the user to take an action outside the app.

    Example: Enable Banking restricted mode requires the user to pre-link
    accounts in the EB portal before sessions return any accounts.
    """

    def __init__(self, message: str, *, code: str, help_url: Optional[str] = None) -> None:
        super().__init__(message)
        self.code = code
        self.help_url = help_url


class ProviderRateLimited(Exception):
    """Raised when the upstream bank/aggregator is throttling data requests.

    Transient and outside the user's control — PSD2 caps unattended account
    access (commonly ~4/day per resource), so a burst of syncs returns HTTP
    429. The connection is healthy; callers should skip this run and retry
    later rather than flag it as errored.
    """


class ProviderNotConfiguredError(Exception):
    """Raised when a connection references a provider missing from the registry.

    This is a server configuration problem, not a bank problem — typically one
    process (e.g. the Celery worker) is not loading the environment that
    enables the provider while the API process is. The credentials are fine,
    so callers must not flip the connection to "error": the reconnect banner
    would send the user chasing the wrong fix (and burning setup tokens).
    """


class FxRateProvider(ABC):
    """Abstract interface for FX rate providers."""

    @property
    @abstractmethod
    def name(self) -> str:
        """Unique provider identifier (e.g. 'openexchangerates')."""
        ...

    @abstractmethod
    async def fetch_latest(self) -> dict[str, Decimal]:
        """Return {currency_code: rate_vs_USD} for latest rates."""
        ...

    @abstractmethod
    async def fetch_historical(self, target_date: date) -> dict[str, Decimal]:
        """Return rates for a specific date."""
        ...


class BankProvider(ABC):
    """Abstract interface for open finance integrations.

    Implement this for each provider (Pluggy, Belvo, etc.)
    to enable bank account syncing via OAuth or widget flow.
    """

    @property
    @abstractmethod
    def name(self) -> str:
        """Unique provider identifier (e.g. 'pluggy', 'belvo')."""
        ...

    @property
    def flow_type(self) -> str:
        """Connection flow type: 'oauth' for redirect-based, 'widget' for embedded widget."""
        return "oauth"

    @property
    def redirect_uri(self) -> str:
        """Provider-specific OAuth redirect URI.

        Each provider reads its own env var (e.g.
        ``PLUGGY_OAUTH_REDIRECT_URI``, ``ENABLE_BANKING_OAUTH_REDIRECT_URI``)
        so different providers can register different URLs in their
        respective dashboards. When unset the URL is derived from
        ``FRONTEND_URL`` so a non-default port or domain works out of the box.
        """
        from app.core.config import get_settings

        settings = get_settings()
        return settings.pluggy_oauth_redirect_uri or default_oauth_redirect_uri()

    async def create_connect_token(
        self, client_user_id: str, item_id: str | None = None
    ) -> ConnectTokenData:
        """Create a connect token for widget-based flows. Override in widget providers."""
        raise NotImplementedError(f"{self.name} does not support widget connect tokens")

    async def list_institutions(
        self, country: Optional[str] = None
    ) -> "InstitutionListData":
        """List supported institutions (banks). Empty by default for providers
        that don't surface a selection step (Pluggy uses its own widget).
        """
        return InstitutionListData(countries=[], institutions=[])

    @abstractmethod
    async def get_oauth_url(
        self,
        redirect_uri: str,
        state: str,
        flow_params: Optional[dict] = None,
    ) -> str:
        """Generate OAuth URL for user to authorize.

        ``flow_params`` carries provider-specific options gathered up-front
        (e.g. EB needs ``{"country": "DE", "institution_name": "Revolut"}``).
        """
        ...

    async def reauth_url(
        self,
        credentials: dict,
        settings: dict,
        redirect_uri: str,
        state: str,
    ) -> str:
        """Build a re-authorization URL for an existing connection whose
        session/consent expired. Default raises — only providers with
        renewable consent (OAuth-redirect) need to override.
        """
        raise NotImplementedError(f"{self.name} does not support reauth_url")

    @abstractmethod
    async def handle_oauth_callback(self, code: str) -> ConnectionData:
        """Exchange OAuth code for access token and fetch initial data."""
        ...

    @abstractmethod
    async def get_accounts(self, credentials: dict) -> list[AccountData]:
        """Fetch accounts for a connection."""
        ...

    @abstractmethod
    async def get_transactions(
        self, credentials: dict, account_external_id: str,
        since: Optional[date] = None, payee_source: str = "auto",
    ) -> list[TransactionData]:
        """Fetch transactions for an account."""
        ...

    @abstractmethod
    async def refresh_credentials(self, credentials: dict) -> dict:
        """Refresh access token if needed."""
        ...

    async def trigger_refresh(self, credentials: dict | None) -> RefreshOutcome:
        """Ask the provider to pull fresh data from the underlying institution.

        Some aggregator providers cache the bank's data on their own side and
        only re-fetch on their own schedule. For those, the value we read on a
        sync may be older than what the bank actually has. When the user asks
        for fresh data, providers that expose an on-demand refresh should
        override this method to trigger it and poll until it completes.

        The default is a no-op (returns ``"skipped"``) — providers whose APIs
        already serve live data on every read don't need to override.
        """
        return "skipped"

    async def get_institution_logo(self, credentials: dict) -> Optional[str]:
        """Return the institution logo URL for an existing connection, or None.

        Used to backfill connections that were linked before logo capture
        existed (the sync layer calls this only when a connection has no
        stored logo). Default is no-op so providers without institution
        logos (e.g. SimpleFin) don't need to implement it.
        """
        return None

    async def get_holdings(self, credentials: dict) -> list[HoldingData]:
        """Fetch investment holdings for a connection.

        Providers that don't expose holdings (cash-only accounts, custom
        script providers without brokerage data, etc.) can rely on the
        default empty list.
        """
        return []

    async def get_bills(self, credentials: dict, account_external_id: str) -> list[BillData]:
        """Fetch credit-card bills (faturas) for an account.

        Providers without a bills endpoint, or non-regulated Pluggy
        connections that don't expose /bills, return the default empty list.
        The sync layer falls back to locally-computed cycle math in that case
        (see app.services.credit_card_service).
        """
        return []