beancount-gocardless 0.1.0__tar.gz

beancount_gocardless-0.1.0/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2018 The Python Packaging Authority
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

beancount_gocardless-0.1.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.3
+Name: beancount-gocardless
+Version: 0.1.0
+Summary: 
+License: MIT
+Requires-Python: >=3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: beancount
+Requires-Dist: beangulp
+Requires-Dist: pyyaml
+Requires-Dist: requests
+Requires-Dist: requests-cache
+Description-Content-Type: text/markdown
+
+

beancount_gocardless-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "beancount-gocardless"
+version = "0.1.0"
+description = ""
+authors = []
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "requests",
+    "requests-cache",
+    "beancount",
+    "beangulp",
+    "pyyaml",
+]
+license = "MIT"
+license-files = ["LICENSE"]
+
+[tool.poetry]
+packages = [{include = "beancount_gocardless", from = "src"}]
+
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

beancount_gocardless-0.1.0/src/beancount_gocardless/cli.py

@@ -0,0 +1,71 @@
+import argparse
+import sys
+import os
+from .client import NordigenClient
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description="Nordigen CLI Utility")
+    parser.add_argument(
+        "mode",
+        choices=["list_banks", "create_link", "list_accounts", "delete_link"],
+        help="Operation mode",
+    )
+    parser.add_argument(
+        "--secret_id",
+        default=os.getenv("NORDIGEN_SECRET_ID"),
+        help="API secret ID (defaults to env var NORDIGEN_SECRET_ID)",
+    )
+    parser.add_argument(
+        "--secret_key",
+        default=os.getenv("NORDIGEN_SECRET_KEY"),
+        help="API secret key (defaults to env var NORDIGEN_SECRET_KEY)",
+    )
+    parser.add_argument(
+        "--country", default="GB", help="Country code for listing banks"
+    )
+    parser.add_argument(
+        "--reference", default="beancount", help="Unique reference for bank linking"
+    )
+    parser.add_argument("--bank", help="Bank ID for linking")
+    return parser.parse_args()
+
+
+def main():
+    args = parse_args()
+
+    if not args.secret_id or not args.secret_key:
+        print(
+            "Error: Secret ID and Secret Key are required (pass as args or set env vars NORDIGEN_SECRET_ID and NORDIGEN_SECRET_KEY)",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    client = NordigenClient(
+        args.secret_id,
+        args.secret_key,
+        {"expire_after": 3600 * 24},
+    )
+
+    if args.mode == "list_banks":
+        banks = client.list_banks(args.country)
+        for b in banks:
+            print(b["name"] + ": " + b["id"])
+    elif args.mode == "create_link":
+        if not args.bank:
+            print("--bank is required for create_link", file=sys.stderr)
+            sys.exit(1)
+        print(client.create_link(args.reference, args.bank))
+    elif args.mode == "list_accounts":
+        accounts = client.list_accounts()
+        for a in accounts:
+            print(
+                f"{a["institution_id"]} {a['name']}: {a['iban']} {a['currency']} ({a['reference']}/{a['id']})"
+            )
+
+    elif args.mode == "delete_link":
+        print(client.delete_link(args.reference))
+
+
+if __name__ == "__main__":
+    main()

beancount_gocardless-0.1.0/src/beancount_gocardless/client.py

@@ -0,0 +1,173 @@
+from datetime import date, timedelta, datetime
+import requests_cache
+import requests
+from typing import Protocol, TypedDict, Optional
+
+
+class CacheOptions(TypedDict, total=False):
+    cache_name: requests_cache.StrOrPath
+    backend: Optional[requests_cache.BackendSpecifier]
+    expire_after: requests_cache.ExpirationTime
+    old_data_on_error: bool
+
+
+class HttpServiceException(Exception):
+    """Exception raised for HTTP service errors."""
+
+    def __init__(self, error, response_text=None):
+        self.error = error
+        self.response_text = response_text
+        super().__init__(f"{error}: {response_text}")
+
+
+class BaseService:
+    """Base class for HTTP services handling authentication and requests."""
+
+    BASE_URL = "https://bankaccountdata.gocardless.com/api/v2"
+
+    DEFAULT_CACHE_OPTIONS: CacheOptions = {
+        "cache_name": "nordigen",
+        "backend": "sqlite",
+        "expire_after": 3600 * 24,
+        "old_data_on_error": False,
+    }
+
+    def __init__(
+        self,
+        secret_id: str,
+        secret_key: str,
+        cache_options: Optional[CacheOptions],
+    ):
+        self.secret_id = secret_id
+        self.secret_key = secret_key
+        self.token = None
+        merged_options = {**self.DEFAULT_CACHE_OPTIONS, **(cache_options or {})}
+        self.session = requests_cache.CachedSession(**merged_options)
+
+    def _ensure_token_valid(self):
+        """Ensure a valid token exists (no-op here as Nordigen doesn't provide refresh tokens)."""
+        if not self.token:
+            self.get_token()
+
+    def get_token(self):
+        """Fetch a new API token using credentials."""
+        response = requests.post(
+            f"{self.BASE_URL}/token/new/",
+            data={"secret_id": self.secret_id, "secret_key": self.secret_key},
+        )
+        self._handle_response(response)
+        self.token = response.json()["access"]
+
+    def _handle_response(self, response):
+        """Check response status and handle errors."""
+        try:
+            response.raise_for_status()
+        except requests.exceptions.HTTPError as e:
+            raise HttpServiceException(str(e), response.text)
+
+    def _request(self, method, endpoint, params=None, data=None):
+        """Execute an HTTP request with token handling."""
+        url = f"{self.BASE_URL}{endpoint}"
+        self._ensure_token_valid()
+        headers = {"Authorization": f"Bearer {self.token}"}
+
+        response = self.session.request(
+            method, url, headers=headers, params=params, data=data
+        )
+
+        # Retry once if token expired
+        if response.status_code == 401:
+            self.get_token()
+            headers = {"Authorization": f"Bearer {self.token}"}
+            response = self.session.request(
+                method, url, headers=headers, params=params, data=data
+            )
+
+        self._handle_response(response)
+        return response
+
+    def _get(self, endpoint, params=None):
+        return self._request("GET", endpoint, params=params).json()
+
+    def _post(self, endpoint, data=None):
+        return self._request("POST", endpoint, data=data).json()
+
+    def _delete(self, endpoint):
+        return self._request("DELETE", endpoint).json()
+
+
+class NordigenClient(BaseService):
+    """Client for interacting with the Nordigen API."""
+
+    def list_banks(self, country="GB"):
+        """List available institutions for a country."""
+        return [
+            {"name": bank["name"], "id": bank["id"]}
+            for bank in self._get("/institutions/", params={"country": country})
+        ]
+
+    def find_requisition_id(self, reference):
+        """Find requisition ID by reference."""
+        requisitions = self._get("/requisitions/")["results"]
+        return next(
+            (req["id"] for req in requisitions if req["reference"] == reference), None
+        )
+
+    def create_link(self, reference, bank_id, redirect_url="http://localhost"):
+        """Create a new bank link requisition."""
+        if self.find_requisition_id(reference):
+            return {"status": "exists", "message": f"Link {reference} exists"}
+
+        response = self._post(
+            "/requisitions/",
+            data={
+                "redirect": redirect_url,
+                "institution_id": bank_id,
+                "reference": reference,
+            },
+        )
+        return {
+            "status": "created",
+            "link": response["link"],
+            "message": f"Complete linking at: {response['link']}",
+        }
+
+    def list_accounts(self):
+        """List all connected accounts with details."""
+        accounts = []
+        for req in self._get("/requisitions/")["results"]:
+            for account_id in req["accounts"]:
+                account = self._get(f"/accounts/{account_id}")
+                details = self._get(f"/accounts/{account_id}/details")["account"]
+
+                accounts.append(
+                    {
+                        "id": account_id,
+                        "institution_id": req.get("institution_id", ""),
+                        "reference": req["reference"],
+                        "iban": account.get("iban", ""),
+                        "currency": details.get("currency", ""),
+                        "name": details.get("name", "Unknown"),
+                    }
+                )
+        return accounts
+
+    def delete_link(self, reference):
+        """Delete a bank link by reference."""
+        req_id = self.find_requisition_id(reference)
+        if not req_id:
+            return {"status": "not_found", "message": f"Link {reference} not found"}
+
+        self._delete(f"/requisitions/{req_id}")
+        return {"status": "deleted", "message": f"Link {reference} removed"}
+
+    def get_transactions(self, account_id, days_back=180):
+        """Retrieve transactions for an account."""
+        date_from = (datetime.now() - timedelta(days=days_back)).strftime("%Y-%m-%d")
+        return self._get(
+            f"/accounts/{account_id}/transactions/",
+            params={
+                "date_from": date_from,
+                "date_to": datetime.now().strftime("%Y-%m-%d"),
+            },
+        ).get("transactions", [])

beancount_gocardless-0.1.0/src/beancount_gocardless/importer.py

@@ -0,0 +1,183 @@
+from datetime import date, timedelta, datetime
+from os import path
+import beangulp
+import yaml
+from beancount.core import amount, data, flags
+from beancount.core.number import D
+from .client import NordigenClient
+
+
+class NordigenImporter(beangulp.Importer):
+    """An importer for Nordigen API with improved structure and extensibility."""
+
+    def __init__(self):
+        self.config = None
+        self._client = None
+
+    @property
+    def client(self):
+        if not self._client:
+            self._client = NordigenClient(
+                self.config["secret_id"],
+                self.config["secret_key"],
+                cache_options={"expire_after": 3600 * 24, "old_data_on_error": True},
+            )
+
+        return self._client
+
+    def identify(self, filepath: str) -> bool:
+        return path.basename(filepath).endswith("nordigen.yaml")
+
+    def account(self, filepath: str) -> str:
+        return ""
+
+    def load_config(self, filepath: str):
+        """Load configuration from YAML file."""
+        with open(filepath, "r") as f:
+            raw_config = f.read()
+            expanded_config = path.expandvars(raw_config)
+            self.config = yaml.safe_load(expanded_config)
+
+        return self.config
+
+    def get_transactions_data(self, account_id):
+        """Get transactions data either from API or debug files."""
+        transactions_data = self.client.get_transactions(account_id)
+
+        return transactions_data
+
+    def get_all_transactions(self, transactions_data):
+        """Combine and sort booked and pending transactions."""
+        all_transactions = [
+            (tx, "booked") for tx in transactions_data.get("booked", [])
+        ] + [(tx, "pending") for tx in transactions_data.get("pending", [])]
+        return sorted(
+            all_transactions,
+            key=lambda x: x[0].get("valueDate") or x[0].get("bookingDate"),
+        )
+
+    def add_metadata(self, transaction, filing_account: str):
+        """Extract metadata from transaction - overridable method."""
+        metakv = {}
+
+        # Transaction ID
+        if "transactionId" in transaction:
+            metakv["nordref"] = transaction["transactionId"]
+
+        # Names
+        if "creditorName" in transaction:
+            metakv["creditorName"] = transaction["creditorName"]
+        if "debtorName" in transaction:
+            metakv["debtorName"] = transaction["debtorName"]
+
+        # Currency exchange
+        if "currencyExchange" in transaction:
+            instructedAmount = transaction["currencyExchange"]["instructedAmount"]
+            metakv["original"] = (
+                f"{instructedAmount['currency']} {instructedAmount['amount']}"
+            )
+
+        # Booking date if different from value date
+        if (
+            transaction.get("bookingDate")
+            and transaction.get("valueDate")
+            and transaction["bookingDate"] != transaction["valueDate"]
+        ):
+            metakv["bookingDate"] = transaction["bookingDate"]
+
+        if filing_account:
+            metakv["filing_account"] = filing_account
+
+        return metakv
+
+    def get_narration(self, transaction):
+        """Extract narration from transaction - overridable method."""
+        narration = ""
+
+        if "remittanceInformationUnstructured" in transaction:
+            narration += transaction["remittanceInformationUnstructured"]
+
+        if "remittanceInformationUnstructuredArray" in transaction:
+            narration += " ".join(transaction["remittanceInformationUnstructuredArray"])
+
+        return narration
+
+    def get_payee(self, transaction):
+        """Extract payee from transaction - overridable method."""
+        return ""
+
+    def get_transaction_date(self, transaction):
+        """Extract transaction date - overridable method."""
+        date_str = transaction.get("valueDate") or transaction.get("bookingDate")
+        return date.fromisoformat(date_str) if date_str else None
+
+    def get_transaction_status(self, status):
+        """Determine transaction status flag - overridable method."""
+        # Could be configured to use "!" for pending transactions status == 'pending'
+        return flags.FLAG_OKAY
+
+    def create_transaction_entry(
+        self, transaction, status, asset_account, filing_account
+    ):
+        """Create a Beancount transaction entry - overridable method."""
+        metakv = self.add_metadata(transaction, filing_account)
+        meta = data.new_metadata("", 0, metakv)
+
+        trx_date = self.get_transaction_date(transaction)
+        narration = self.get_narration(transaction)
+        payee = self.get_payee(transaction)
+        flag = self.get_transaction_status(status)
+
+        # Get transaction amount
+        tx_amount = amount.Amount(
+            D(str(transaction["transactionAmount"]["amount"])),
+            transaction["transactionAmount"]["currency"],
+        )
+
+        return data.Transaction(
+            meta,
+            trx_date,
+            flag,
+            payee,
+            narration,
+            data.EMPTY_SET,
+            data.EMPTY_SET,
+            [
+                data.Posting(
+                    asset_account,
+                    tx_amount,
+                    None,
+                    None,
+                    None,
+                    None,
+                ),
+            ],
+        )
+
+    def extract(self, filepath: str, existing: data.Entries) -> data.Entries:
+        """Extract entries from Nordigen transactions."""
+        self.load_config(filepath)
+
+        entries = []
+        for account in self.config["accounts"]:
+            account_id = account["id"]
+            asset_account = account["asset_account"]
+            filing_account = account.get("filing_account", None)
+
+            transactions_data = self.get_transactions_data(account_id)
+            all_transactions = self.get_all_transactions(transactions_data)
+
+            for transaction, status in all_transactions:
+                entry = self.create_transaction_entry(
+                    transaction, status, asset_account, filing_account
+                )
+                entries.append(entry)
+
+        return entries
+
+    def cmp(self, entry1: data.Transaction, entry2: data.Transaction):
+        return (
+            "nordref" in entry1.meta
+            and "nordref" in entry2.meta
+            and entry1.meta["nordref"] == entry2.meta["nordref"]
+        )