beancount-gocardless 0.1.0__tar.gz → 0.1.2__tar.gz

beancount_gocardless-0.1.2/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.3
+Name: beancount-gocardless
+Version: 0.1.2
+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
+====================
+
+This package provides a basic client for interacting with the GoCardless API (formerly Nordigen) and importing your data into Beancount.
+
+This project was inspired by https://github.com/tarioch/beancounttools
+
+Full documentation available at https://beancount-gocardless.readthedocs.io/en/latest/
+
+
+**Key Features:**
+
+- **GoCardless API Client:**  A client for interacting with the GoCardless API. The client has built-in caching via `requests-cache`.
+- **GoCardLess CLI**\: A command-line interface to manage authorization with the GoCardless API:
+
+    - Listing available banks in a specified country (default: GB).
+    - Creating a link to a specific bank using its ID.
+    - Listing authorized accounts.
+    - Deleting an existing link.
+    - Uses environment variables (`NORDIGEN_SECRET_ID`, `NORDIGEN_SECRET_KEY`) or command-line arguments for API credentials.
+- **Beancount Importer:**  A `beangulp.Importer` implementation to easily import transactions fetched from the GoCardless API directly into your Beancount ledger.
+
+You'll need to create a GoCardLess account on https://bankaccountdata.gocardless.com/overview/ to get your credentials.
+
+**Installation:**
+
+```bash
+pip install beancount-gocardless
+```
+
+**Usage**
+```yaml
+#### nordigen.yaml
+secret_id: $NORDIGEN_SECRET_ID
+secret_key: $NORDIGEN_SECRET_KEY
+
+cache_options: # by default, no caching if cache_options is not provided
+  cache_name: "nordigen"
+  backend: "sqlite"
+  expire_after: 3600
+  old_data_on_error: true
+
+accounts:
+    - id: <REDACTED_UUID>
+    asset_account: "Assets:Banks:Revolut:Checking"
+```
+
+```python
+#### my.import
+#!/usr/bin/env python
+
+import beangulp
+from beancount_gocardless import NordigenImporter
+from smart_importer import apply_hooks, PredictPostings, PredictPayees
+
+importers = [
+    apply_hooks(
+        NordigenImporter(),
+        [
+            PredictPostings(),
+            PredictPayees(),
+        ],
+    )
+]
+
+if __name__ == "__main__":
+    ingest = beangulp.Ingest(importers)
+    ingest()
+```
+
+Import your data from Nordigen's API
+```bash
+python my.import extract ./nordigen.yaml --existing ./ledger.bean
+```
+

beancount_gocardless-0.1.2/README.md

@@ -0,0 +1,74 @@
+beancount-gocardless
+====================
+
+This package provides a basic client for interacting with the GoCardless API (formerly Nordigen) and importing your data into Beancount.
+
+This project was inspired by https://github.com/tarioch/beancounttools
+
+Full documentation available at https://beancount-gocardless.readthedocs.io/en/latest/
+
+
+**Key Features:**
+
+- **GoCardless API Client:**  A client for interacting with the GoCardless API. The client has built-in caching via `requests-cache`.
+- **GoCardLess CLI**\: A command-line interface to manage authorization with the GoCardless API:
+
+    - Listing available banks in a specified country (default: GB).
+    - Creating a link to a specific bank using its ID.
+    - Listing authorized accounts.
+    - Deleting an existing link.
+    - Uses environment variables (`NORDIGEN_SECRET_ID`, `NORDIGEN_SECRET_KEY`) or command-line arguments for API credentials.
+- **Beancount Importer:**  A `beangulp.Importer` implementation to easily import transactions fetched from the GoCardless API directly into your Beancount ledger.
+
+You'll need to create a GoCardLess account on https://bankaccountdata.gocardless.com/overview/ to get your credentials.
+
+**Installation:**
+
+```bash
+pip install beancount-gocardless
+```
+
+**Usage**
+```yaml
+#### nordigen.yaml
+secret_id: $NORDIGEN_SECRET_ID
+secret_key: $NORDIGEN_SECRET_KEY
+
+cache_options: # by default, no caching if cache_options is not provided
+  cache_name: "nordigen"
+  backend: "sqlite"
+  expire_after: 3600
+  old_data_on_error: true
+
+accounts:
+    - id: <REDACTED_UUID>
+    asset_account: "Assets:Banks:Revolut:Checking"
+```
+
+```python
+#### my.import
+#!/usr/bin/env python
+
+import beangulp
+from beancount_gocardless import NordigenImporter
+from smart_importer import apply_hooks, PredictPostings, PredictPayees
+
+importers = [
+    apply_hooks(
+        NordigenImporter(),
+        [
+            PredictPostings(),
+            PredictPayees(),
+        ],
+    )
+]
+
+if __name__ == "__main__":
+    ingest = beangulp.Ingest(importers)
+    ingest()
+```
+
+Import your data from Nordigen's API
+```bash
+python my.import extract ./nordigen.yaml --existing ./ledger.bean
+```

{beancount_gocardless-0.1.0 → beancount_gocardless-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "beancount-gocardless"
-version = "0.1.0"
+version = "0.1.2"
 description = ""
 authors = []
 readme = "README.md"
@@ -19,6 +19,16 @@ license-files = ["LICENSE"]
 packages = [{include = "beancount_gocardless", from = "src"}]
 
 
+[tool.poetry.group.dev.dependencies]
+sphinx = "*"
+sphinx-rtd-theme = "*"
+myst_parser = "*"
+pre-commit = "*"
+
+[tool.poetry.group.lint.dependencies]
+ruff = ">=0.9.8"
+
+
 [build-system]
 requires = ["poetry-core>=2.0.0,<3.0.0"]
 build-backend = "poetry.core.masonry.api"

beancount_gocardless-0.1.2/src/beancount_gocardless/__init__.py

@@ -0,0 +1,2 @@
+from .client import NordigenClient # noqa: F401
+from .importer import NordigenImporter # noqa: F401

{beancount_gocardless-0.1.0 → beancount_gocardless-0.1.2}/src/beancount_gocardless/cli.py

@@ -5,6 +5,12 @@ from .client import NordigenClient
 
 
 def parse_args():
+    """
+    Parses command-line arguments.
+
+    Returns:
+        argparse.Namespace: An object containing the parsed arguments.
+    """
     parser = argparse.ArgumentParser(description="Nordigen CLI Utility")
     parser.add_argument(
         "mode",
@@ -32,6 +38,11 @@ def parse_args():
 
 
 def main():
+    """
+    The main entry point for the CLI.
+
+    Executes the specified operation based on the parsed command-line arguments.
+    """
     args = parse_args()
 
     if not args.secret_id or not args.secret_key:
@@ -44,7 +55,7 @@ def main():
     client = NordigenClient(
         args.secret_id,
         args.secret_key,
-        {"expire_after": 3600 * 24},
+        {},
     )
 
     if args.mode == "list_banks":
@@ -60,7 +71,7 @@ def main():
         accounts = client.list_accounts()
         for a in accounts:
             print(
-                f"{a["institution_id"]} {a['name']}: {a['iban']} {a['currency']} ({a['reference']}/{a['id']})"
+                f"{a['institution_id']} {a['name']}: {a['iban']} {a['currency']} ({a['reference']}/{a['id']})"
             )
 
     elif args.mode == "delete_link":

beancount_gocardless-0.1.2/src/beancount_gocardless/client.py

@@ -0,0 +1,342 @@
+from datetime import timedelta, datetime
+import requests_cache
+import requests
+from typing import TypedDict, Optional
+
+
+class CacheOptions(TypedDict, total=False):
+    """
+    Options for configuring requests-cache.
+
+    Attributes:
+        cache_name (str, optional): The name of the cache. Defaults to 'nordigen'.  Can also be a path.
+        backend (str, optional): The cache backend to use (e.g., 'sqlite', 'memory'). Defaults to 'sqlite'.
+        expire_after (int, optional): The cache expiration time in seconds. Defaults to 86400 (24 hours).
+        old_data_on_error (bool, optional): Whether to return old cached data on a request error. Defaults to 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.  This wraps HTTP errors from the underlying requests library.
+
+    Attributes:
+        error (str): The original error message.
+        response_text (str, optional): The full response text from the server.
+    """
+
+    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 to the GoCardless Bank Account Data API.
+
+    Attributes:
+        BASE_URL (str): The base URL for the API.
+        DEFAULT_CACHE_OPTIONS (CacheOptions): Default caching options.
+        secret_id (str): Your GoCardless API secret ID.
+        secret_key (str): Your GoCardless API secret key.
+        token (str, optional): The current API access token.
+        session (requests_cache.CachedSession): The cached requests session.
+    """
+
+    BASE_URL = "https://bankaccountdata.gocardless.com/api/v2"
+
+    DEFAULT_CACHE_OPTIONS: CacheOptions = {
+        "cache_name": "nordigen",
+        "backend": "sqlite",
+        "expire_after": 0,
+        "old_data_on_error": False,
+    }
+
+    def __init__(
+        self,
+        secret_id: str,
+        secret_key: str,
+        cache_options: Optional[CacheOptions],
+    ):
+        """
+        Initializes the BaseService.
+
+        Args:
+            secret_id (str): Your GoCardless API secret ID.
+            secret_key (str): Your GoCardless API secret key.
+            cache_options (CacheOptions, optional):  Custom cache options.  Merges with and overrides DEFAULT_CACHE_OPTIONS.
+        """
+        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.  Gets a new token if one doesn't exist.
+        Nordigen tokens don't currently have a refresh mechanism, so this just gets a new one if needed.
+        """
+        if not self.token:
+            self.get_token()
+
+    def get_token(self):
+        """
+        Fetch a new API access token using credentials. Sets the `self.token` attribute.
+
+        Raises:
+            HttpServiceException: If the API request fails.
+        """
+        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.
+
+        Args:
+            response (requests.Response): The response object from the API request.
+
+        Raises:
+            HttpServiceException: If the API request returns an error status code.
+        """
+        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 and automatic retries.
+
+        Args:
+            method (str): The HTTP method (e.g., "GET", "POST", "DELETE").
+            endpoint (str): The API endpoint (relative to BASE_URL).
+            params (dict, optional): URL parameters for the request.
+            data (dict, optional): Data to send in the request body (for POST requests).
+
+        Returns:
+            requests.Response: The response object from the API request.
+
+        Raises:
+            HttpServiceException: If the API request fails.
+        """
+        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 (401 Unauthorized)
+        if response.status_code == 401:
+            self.get_token()  # Get a new token
+            headers = {"Authorization": f"Bearer {self.token}"}  # Update headers
+            response = self.session.request(
+                method, url, headers=headers, params=params, data=data
+            )
+
+        self._handle_response(response)
+        return response
+
+    def _get(self, endpoint, params=None):
+        """
+        Perform a GET request and return the JSON response.
+
+        Args:
+            endpoint (str): The API endpoint.
+            params (dict, optional): URL parameters.
+
+        Returns:
+            dict: The JSON response from the API.
+        """
+        return self._request("GET", endpoint, params=params).json()
+
+    def _post(self, endpoint, data=None):
+        """
+        Perform a POST request and return the JSON response.
+
+        Args:
+            endpoint (str): The API endpoint.
+            data (dict, optional): Data to send in the request body.
+
+        Returns:
+            dict: The JSON response from the API.
+        """
+        return self._request("POST", endpoint, data=data).json()
+
+    def _delete(self, endpoint):
+        """
+        Perform a DELETE request and return the JSON response.
+
+        Args:
+            endpoint (str): The API endpoint.
+
+        Returns:
+            dict: The JSON response from the API.
+        """
+        return self._request("DELETE", endpoint).json()
+
+
+class NordigenClient(BaseService):
+    """
+    Client for interacting with the Nordigen API (GoCardless Bank Account Data).
+
+    This class provides methods for listing banks, creating and managing requisitions (links),
+    listing accounts, deleting links, and retrieving transactions. It inherits from `BaseService`
+    to handle authentication and HTTP requests.
+    """
+
+    def list_banks(self, country="GB"):
+        """
+        List available institutions (banks) for a given country.
+
+        Args:
+            country (str, optional): The two-letter country code (ISO 3166). Defaults to "GB".
+
+        Returns:
+            list: A list of dictionaries, each containing the 'name' and 'id' of a bank.
+
+        Example:
+            ```python
+            client = NordigenClient(...)
+            banks = client.list_banks(country="US")
+            for bank in banks:
+                print(f"{bank['name']} (ID: {bank['id']})")
+            ```
+        """
+        return [
+            {"name": bank["name"], "id": bank["id"]}
+            for bank in self._get("/institutions/", params={"country": country})
+        ]
+
+    def find_requisition_id(self, reference):
+        """
+        Find a requisition ID by its reference string.
+
+        Args:
+            reference (str): The unique reference string associated with the requisition.
+
+        Returns:
+            str or None: The requisition ID if found, otherwise None.
+        """
+        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.
+
+        Args:
+            reference (str): A unique reference string for this link.
+            bank_id (str): The ID of the institution (bank) to link to.
+            redirect_url (str, optional): The URL to redirect the user to after authentication. Defaults to "http://localhost".
+
+        Returns:
+            dict: A dictionary with the status of the operation.  If successful, includes the link URL.
+                - status: "exists" if a requisition with the given `reference` already exists, "created" otherwise
+                - message: A descriptive message
+                - link: (If status is "created") The URL to start the linking process.
+
+        Example:
+            ```python
+            client = NordigenClient(...)
+            result = client.create_link(reference="my-unique-ref", bank_id="SANDBOXFINANCE_SFIN0000")
+            if result["status"] == "created":
+                print(f"Redirect user to: {result['link']}")
+            else:
+                print(result["message"])
+            ```
+        """
+        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 (ID, institution, reference, IBAN, currency, name).
+
+        Returns:
+            list: A list of dictionaries, each representing a connected account.
+        """
+        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 (requisition) by its reference.
+
+        Args:
+            reference (str): The unique reference string of the link to delete.
+
+        Returns:
+            dict: A dictionary with the status and a message.  Status can be "deleted" or "not_found".
+        """
+        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 a given account.
+
+        Args:
+            account_id (str): The ID of the account.
+            days_back (int, optional): The number of days back to retrieve transactions for. Defaults to 180.
+
+        Returns:
+            dict: The 'transactions' part of the API response, or an empty dict if no transactions are found.
+              See the Nordigen API documentation for the structure of this data.
+        """
+        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.2/src/beancount_gocardless/importer.py

@@ -0,0 +1,345 @@
+from datetime import date
+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.
+
+    Attributes:
+        config (dict): Configuration loaded from the YAML file.
+        _client (NordigenClient): Instance of the Nordigen API client.
+
+    """
+
+    def __init__(self):
+        """Initialize the NordigenImporter."""
+        self.config = None
+        self._client = None
+
+    @property
+    def client(self):
+        """
+        Lazily initializes and returns the Nordigen API client.
+
+        Returns:
+            NordigenClient: The initialized Nordigen API client.
+        """
+        if not self._client:
+            self._client = NordigenClient(
+                self.config["secret_id"],
+                self.config["secret_key"],
+                cache_options=self.config.get('cache_options', None),
+            )
+
+        return self._client
+
+    def identify(self, filepath: str) -> bool:
+        """
+        Identifies if the given file is a Nordigen configuration file.
+
+        Args:
+            filepath (str): The path to the file.
+
+        Returns:
+            bool: True if the file is a Nordigen configuration file, False otherwise.
+        """
+        return path.basename(filepath).endswith("nordigen.yaml")
+
+    def account(self, filepath: str) -> str:
+        """
+        Returns an empty string as account (not directly used in this importer).
+
+        Args:
+            filepath (str): The path to the file.  Not used in this implementation.
+
+        Returns:
+            str: An empty string.
+        """
+        return ""  # We get the account from the config file
+
+    def load_config(self, filepath: str):
+        """
+        Loads configuration from the specified YAML file.
+
+        Args:
+            filepath (str): The path to the YAML configuration file.
+
+        Returns:
+            dict: The loaded configuration dictionary.  Also sets the `self.config` attribute.
+        """
+        with open(filepath, "r") as f:
+            raw_config = f.read()
+            expanded_config = path.expandvars(
+                raw_config
+            )  # Handle environment variables
+            self.config = yaml.safe_load(expanded_config)
+
+        return self.config
+
+    def get_transactions_data(self, account_id):
+        """
+        Retrieves transaction data for a given account ID from the Nordigen API.
+
+        Args:
+            account_id (str): The Nordigen account ID.
+
+        Returns:
+            dict: The transaction data returned by the API.
+        """
+        transactions_data = self.client.get_transactions(account_id)
+
+        return transactions_data
+
+    def get_all_transactions(self, transactions_data):
+        """
+        Combines booked and pending transactions and sorts them by date.
+
+        Args:
+            transactions_data (dict): The transaction data from the API,
+                containing 'booked' and 'pending' lists.
+
+        Returns:
+            list: A sorted list of tuples, where each tuple contains
+                a transaction dictionary and its status ('booked' or 'pending').
+        """
+        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):
+        """
+        Extracts metadata from a transaction and returns it as a dictionary.
+
+        This method can be overridden in subclasses to customize metadata extraction.
+
+        Args:
+            transaction (dict): The transaction data from the API.
+            filing_account (str):  The optional filing account from the configuration.
+
+        Returns:
+            dict: A dictionary of metadata key-value pairs.
+        """
+        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):
+        """
+        Extracts the narration from a transaction.
+
+        This method can be overridden in subclasses to customize narration extraction.
+
+        Args:
+            transaction (dict): The transaction data from the API.
+
+        Returns:
+            str: The extracted narration.
+        """
+        narration = ""
+
+        if "remittanceInformationUnstructured" in transaction:
+            narration += transaction["remittanceInformationUnstructured"]
+
+        if "remittanceInformationUnstructuredArray" in transaction:
+            narration += " ".join(transaction["remittanceInformationUnstructuredArray"])
+
+        return narration
+
+    def get_payee(self, transaction):
+        """
+        Extracts the payee from a transaction.
+
+        This method can be overridden in subclasses to customize payee extraction.  The default
+        implementation returns an empty string.
+
+        Args:
+            transaction (dict):  The transaction data from the API.
+
+        Returns:
+            str: The extracted payee (or an empty string by default).
+
+        """
+        return ""
+
+    def get_transaction_date(self, transaction):
+        """
+        Extracts the transaction date from a transaction.  Prefers 'valueDate',
+        falls back to 'bookingDate'.
+
+        This method can be overridden in subclasses to customize date extraction.
+
+        Args:
+            transaction (dict): The transaction data from the API.
+
+        Returns:
+            date: The extracted transaction date, or None if no date is found.
+        """
+        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):
+        """
+        Determines the Beancount transaction flag based on the transaction status.
+
+        This method can be overridden in subclasses to customize flag assignment. The default
+        implementation returns FLAG_OKAY for all transactions.
+
+        Args:
+            status (str): The transaction status ('booked' or 'pending').
+
+        Returns:
+            str: The Beancount transaction flag.
+        """
+        # 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
+    ):
+        """
+        Creates a Beancount transaction entry from a Nordigen transaction.
+
+        This method can be overridden in subclasses to customize entry creation.
+
+        Args:
+            transaction (dict): The transaction data from the API.
+            status (str): The transaction status ('booked' or 'pending').
+            asset_account (str): The Beancount asset account.
+            filing_account (str): The optional filing account.
+
+        Returns:
+            data.Transaction: The created Beancount transaction entry.
+        """
+        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:
+        """
+        Extracts Beancount entries from Nordigen transactions.
+
+        Args:
+            filepath (str): The path to the YAML configuration file.
+            existing (data.Entries):  Existing Beancount entries (not used in this implementation).
+
+        Returns:
+            data.Entries: A list of Beancount transaction entries.
+        """
+        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):
+        """
+        Compares two transactions based on their 'nordref' metadata.
+
+        Used for sorting transactions.  This assumes that 'nordref' is a unique
+        identifier for each transaction.
+
+        Args:
+           entry1 (data.Transaction): The first transaction.
+           entry2 (data.Transaction): The second transaction.
+
+        Returns:
+            int: -1 if entry1 < entry2, 0 if entry1 == entry2, 1 if entry1 > entry2.
+                 Returns 0 if 'nordref' is not present in both.
+        """
+        if (
+            "nordref" in entry1.meta
+            and "nordref" in entry2.meta
+            and entry1.meta["nordref"] == entry2.meta["nordref"]
+        ):
+            return 0  # Consider them equal if nordref matches
+        elif (
+            "nordref" in entry1.meta
+            and "nordref" in entry2.meta
+            and entry1.meta["nordref"] < entry2.meta["nordref"]
+        ):
+            return -1
+        elif "nordref" in entry1.meta and "nordref" in entry2.meta:
+            return 1
+        else:
+            return 0

beancount_gocardless-0.1.0/PKG-INFO

@@ -1,18 +0,0 @@
-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/src/beancount_gocardless/client.py

@@ -1,173 +0,0 @@
-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

@@ -1,183 +0,0 @@
-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"]
-        )