Files
WYGIWYH/app/apps/bank_sync/providers/base.py
T
Herculino Trotta 2a4202118b feat(bank-sync): import pending transactions and settle them when they post
Providers can now return pending transactions, flagged as such, when
their ids survive posting. They're imported unpaid right away and, once
the bank posts them, marked paid with their final amount and date.

- Settling happens once, so later edits stick, and one marked paid by
  hand is left alone. It goes through save() so a transfer's other side
  follows; no rules run again. reference_date moves only if it still
  followed the date.
- Each sync looks back to the oldest unpaid synced transaction, since a
  card purchase can post weeks later when the bill closes. Pending ones
  older than 60 days are taken as cancelled and no longer followed.
2026-11-08 16:09:23 -03:00

63 lines
1.8 KiB
Python

from abc import ABC, abstractmethod
from dataclasses import dataclass
from datetime import date
from decimal import Decimal
@dataclass(frozen=True)
class RemoteAccount:
id: str
name: str
# Currency codes as the provider spells them
currencies: tuple = ()
# Why the account can't be synced right now (expired connection...), empty if fine
error: str = ""
@dataclass(frozen=True)
class RemoteTransaction:
id: str
date: date
# Signed: negative is money leaving the account
amount: Decimal
description: str = ""
notes: str = ""
currency: str = ""
# Not settled yet. Imported unpaid and updated when it posts, so only return
# these when the provider keeps the id once they post
pending: bool = False
class BankSyncProvider(ABC):
"""A bank data aggregator.
``settings_fields`` declares the provider's own configuration as Django form
fields. The service form renders them when the provider is selected and the
values end up in ``BankSyncService.settings`` under the same keys.
"""
settings_fields: dict = {}
# In hours, for services that limit how often they can be called
min_sync_interval: int = 1
def __init__(self, settings: dict):
self.settings = settings or {}
@classmethod
def clean_settings(cls, settings: dict) -> dict:
"""Validate or transform the settings before they're saved.
Runs once every other form field is valid. Raise ValidationError to reject.
"""
return settings
@abstractmethod
def list_accounts(self) -> list[RemoteAccount]:
"""Every account the credentials can see."""
@abstractmethod
def get_transactions(
self, account_id: str, start_date: date
) -> list[RemoteTransaction]:
"""Posted transactions of ``account_id`` dated ``start_date`` or later."""