beancount-gocardless 0.1.7__py3-none-any.whl → 0.1.9__py3-none-any.whl

beancount_gocardless/client.py

@@ -1,368 +1,424 @@
-from datetime import timedelta, datetime
+"""
+GoCardless Bank Account Data API Client
+Clean, typed, auto-generated client with full caching and header stripping
+"""
+
+import logging
+from typing import Optional, Dict, Any, List
+from datetime import datetime, timedelta
 import requests_cache
 import requests
-from typing import TypedDict, Optional
-import logging
+from .models import (
+    Account,
+    AccountBalance,
+    AccountDetail,
+    AccountTransactions,
+    Institution,
+    Requisition,
+    EndUserAgreement,
+    ReconfirmationRetrieve,
+    PaginatedRequisitionList,
+    PaginatedEndUserAgreementList,
+    Integration,
+    IntegrationRetrieve,
+    SpectacularJWTObtain,
+    SpectacularJWTRefresh,
+    AccountInfo,
+)
 
 logger = logging.getLogger(__name__)
 
 
-def cleanup_headers(response):
+def strip_headers_hook(response, *args, **kwargs):
+    """
+    Strip response headers to reduce cache size and improve privacy.
+    Only preserves essential headers needed for proper operation.
+    """
     to_preserve = [
         "Content-Type",
         "Date",
         "Content-Encoding",
         "Content-Language",
-        "ETag",
         "Last-Modified",
+        "Location",
     ]
     deleted = set()
     to_preserve_lower = [h.lower() for h in to_preserve]
-    for header in response.headers.keys():
-        if header.lower() not in to_preserve_lower:
-            del response.headers[header]
+    header_keys_to_check = response.headers.copy().keys()
+    for header in header_keys_to_check:
+        if header.lower() in to_preserve_lower:
+            continue
+        else:
+            response.headers.pop(header, None)
             deleted.add(header)
-    logger.info("Deleted headers: %s", ", ".join(deleted))
+    logger.debug("Deleted headers: %s", ", ".join(deleted))
     return response
 
 
-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:
+class GoCardlessClient:
     """
-    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.
+    Clean, typed GoCardless Bank Account Data API client with full caching support.
     """
 
     BASE_URL = "https://bankaccountdata.gocardless.com/api/v2"
 
-    DEFAULT_CACHE_OPTIONS: CacheOptions = {
-        "cache_name": "nordigen",
-        "backend": "sqlite",
-        "expire_after": 0,
-        "old_data_on_error": True,
-        "match_headers": False,
-        "cache_control": False,
-        "response_hook": cleanup_headers,
-    }
-
     def __init__(
         self,
         secret_id: str,
         secret_key: str,
-        cache_options: Optional[CacheOptions],
+        cache_options: Optional[Dict[str, Any]] = None,
     ):
-        """
-        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.
-        """
+        logger.info("Initializing GoCardlessClient")
         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)
+        self._token: Optional[str] = None
+
+        # Default cache options that match the original client
+        default_cache_options = {
+            "cache_name": "gocardless",
+            "backend": "sqlite",
+            "expire_after": 0,
+            "old_data_on_error": True,
+            "match_headers": False,
+            "cache_control": False,
+        }
+
+        # Merge with provided options
+        cache_config = {**default_cache_options, **(cache_options or {})}
+        logger.debug("Cache config: %s", cache_config)
+
+        # Create cached session with header stripping
+        self.session = requests_cache.CachedSession(**cache_config)
+        self.session.hooks["response"].append(strip_headers_hook)
+
+    def check_cache_status(self, method: str, url: str, params=None, data=None) -> dict:
+        """
+        Check cache status for a given request.
+        This mimics the original client's cache checking functionality.
+        """
+        headers = {"Authorization": f"Bearer {self._token}"} if self._token else {}
+
+        req = requests.Request(method, url, params=params, data=data, headers=headers)
+        prepared_request: requests.PreparedRequest = self.session.prepare_request(req)
+        cache = self.session.cache
+        cache_key = cache.create_key(prepared_request)
+        key_exists = cache.contains(cache_key)
+        is_expired = None
+
+        if key_exists:
+            try:
+                cached_response = cache.get_response(cache_key)
+                if cached_response:
+                    is_expired = cached_response.is_expired
+                else:
+                    key_exists = False
+                    is_expired = True
+            except Exception as e:
+                logger.error(
+                    f"Error checking expiration for cache key {cache_key}: {e}"
+                )
+                is_expired = None
 
-    def _ensure_token_valid(self):
+        return {
+            "key_exists": key_exists,
+            "is_expired": is_expired,
+            "cache_key": cache_key,
+        }
+
+    @property
+    def token(self) -> str:
         """
-        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.
+        Get or refresh access token.
         """
-        if not self.token:
+        if not self._token:
             self.get_token()
+        return self._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.
+        Fetch a new API access token using credentials.
         """
+        logger.debug("Fetching new access token")
         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.
+        response.raise_for_status()
+        self._token = response.json()["access"]
+        logger.debug("Access token obtained")
 
-        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.
-        """
+    def _request(self, method: str, endpoint: str, **kwargs) -> requests.Response:
+        """Make authenticated request with caching"""
         url = f"{self.BASE_URL}{endpoint}"
-        self._ensure_token_valid()
-        headers = {"Authorization": f"Bearer {self.token}"}
+        headers = kwargs.pop("headers", {})
+        headers["Authorization"] = f"Bearer {self.token}"
 
-        response = self.session.request(
-            method, url, headers=headers, params=params, data=data
+        # Check cache status for logging
+        status = self.check_cache_status(
+            method, url, kwargs.get("params"), kwargs.get("data")
+        )
+        logger.debug(
+            f"{endpoint}: {'expired' if status.get('is_expired') else 'cache ok'}"
         )
-        logger.info("Response headers", response.headers)
 
-        # Retry once if token expired (401 Unauthorized)
+        response = self.session.request(method, url, headers=headers, **kwargs)
+        logger.debug("Response headers: %s", response.headers)
+
+        # Handle 401 by refreshing token
         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.get_token()
+            headers["Authorization"] = f"Bearer {self.token}"
+            response = self.session.request(method, url, headers=headers, **kwargs)
 
-        self._handle_response(response)
+        response.raise_for_status()
         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 get(self, endpoint: str, params: Optional[Dict] = None) -> Dict[str, Any]:
+        """Make GET request"""
+        response = self._request("GET", endpoint, params=params)
+        return response.json()
+
+    def post(self, endpoint: str, data: Optional[Dict] = None) -> Dict[str, Any]:
+        """Make POST request"""
+        response = self._request("POST", endpoint, data=data)
+        return response.json()
+
+    def delete(self, endpoint: str) -> Dict[str, Any]:
+        """Make DELETE request"""
+        response = self._request("DELETE", endpoint)
+        return response.json()
+
+    # Account methods
+    def get_account(self, account_id: str) -> Account:
+        """Get account metadata"""
+        logger.debug("Getting account metadata for %s", account_id)
+        data = self.get(f"/accounts/{account_id}/")
+        return Account(**data)
+
+    def get_account_balances(self, account_id: str) -> AccountBalance:
+        """Get account balances"""
+        logger.debug("Getting account balances for %s", account_id)
+        data = self.get(f"/accounts/{account_id}/balances/")
+        return AccountBalance(**data)
+
+    def get_account_details(self, account_id: str) -> AccountDetail:
+        """Get account details"""
+        logger.debug("Getting account details for %s", account_id)
+        data = self.get(f"/accounts/{account_id}/details/")
+        return AccountDetail(**data)
+
+    def get_account_transactions(
+        self, account_id: str, days_back: int = 180
+    ) -> AccountTransactions:
+        """Get account transactions"""
+        date_from = (datetime.now() - timedelta(days=days_back)).strftime("%Y-%m-%d")
+        date_to = datetime.now().strftime("%Y-%m-%d")
+        logger.debug(
+            "Fetching transactions for account %s from %s to %s",
+            account_id,
+            date_from,
+            date_to,
         )
 
-    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,
-            },
+        data = self.get(
+            f"/accounts/{account_id}/transactions/",
+            params={"date_from": date_from, "date_to": date_to},
         )
-        return {
-            "status": "created",
-            "link": response["link"],
-            "message": f"Complete linking at: {response['link']}",
+        booked_count = len(data.get("transactions", {}).get("booked", []))
+        pending_count = len(data.get("transactions", {}).get("pending", []))
+        logger.debug(
+            "Fetched %d booked and %d pending transactions for account %s",
+            booked_count,
+            pending_count,
+            account_id,
+        )
+        return AccountTransactions(**data)
+
+    # Institutions methods
+    def get_institutions(self, country: Optional[str] = None) -> List[Institution]:
+        """Get institutions for a country"""
+        logger.debug("Getting institutions for country %s", country)
+        params = {"country": country} if country else {}
+        data = self.get("/institutions/", params=params)
+        logger.debug("Fetched %d institutions", len(data))
+        return [Institution(**inst) for inst in data]
+
+    def get_institution(self, institution_id: str) -> Institution:
+        """Get specific institution"""
+        data = self.get(f"/institutions/{institution_id}/")
+        return Institution(**data)
+
+    # Requisitions methods
+    def create_requisition(
+        self, redirect: str, institution_id: str, reference: str, **kwargs
+    ) -> Requisition:
+        """Create a new requisition"""
+        request_data = {
+            "redirect": redirect,
+            "institution_id": institution_id,
+            "reference": reference,
         }
+        request_data.update(kwargs)
+        data = self.post("/requisitions/", data=request_data)
+        return Requisition(**data)
+
+    def get_requisitions(self) -> List[Requisition]:
+        """Get all requisitions"""
+        logger.debug("Getting all requisitions")
+        data = self.get("/requisitions/")
+        logger.debug("Fetched %d requisitions", len(data.get("results", [])))
+        return [Requisition(**req) for req in data.get("results", [])]
+
+    def get_requisition(self, requisition_id: str) -> Requisition:
+        """Get specific requisition"""
+        data = self.get(f"/requisitions/{requisition_id}/")
+        return Requisition(**data)
+
+    def delete_requisition(self, requisition_id: str) -> Dict[str, Any]:
+        """Delete a requisition"""
+        return self.delete(f"/requisitions/{requisition_id}/")
+
+    # Agreements methods
+    def create_agreement(
+        self,
+        institution_id: str,
+        max_historical_days: int,
+        access_valid_for_days: int,
+        access_scope: List[str],
+        **kwargs,
+    ) -> EndUserAgreement:
+        """Create end user agreement"""
+        request_data = {
+            "institution_id": institution_id,
+            "max_historical_days": max_historical_days,
+            "access_valid_for_days": access_valid_for_days,
+            "access_scope": access_scope,
+        }
+        request_data.update(kwargs)
+        data = self.post("/agreements/enduser/", data=request_data)
+        return EndUserAgreement(**data)
+
+    def get_agreements(self) -> List[EndUserAgreement]:
+        """Get all agreements"""
+        data = self.get("/agreements/enduser/")
+        return [EndUserAgreement(**ag) for ag in data.get("results", [])]
+
+    def get_agreement(self, agreement_id: str) -> EndUserAgreement:
+        """Get specific agreement"""
+        data = self.get(f"/agreements/enduser/{agreement_id}/")
+        return EndUserAgreement(**data)
+
+    def accept_agreement(
+        self, agreement_id: str, user_agent: str, ip: str
+    ) -> Dict[str, Any]:
+        """Accept an agreement"""
+        data = self.post(
+            f"/agreements/enduser/{agreement_id}/accept/",
+            data={"user_agent": user_agent, "ip": ip},
+        )
+        return data
+
+    def reconfirm_agreement(
+        self, agreement_id: str, user_agent: str, ip: str
+    ) -> ReconfirmationRetrieve:
+        """Reconfirm an agreement"""
+        data = self.post(
+            f"/agreements/enduser/{agreement_id}/reconfirm/",
+            data={"user_agent": user_agent, "ip": ip},
+        )
+        return ReconfirmationRetrieve(**data)
 
-    def list_accounts(self):
-        """
-        List all connected accounts with details (ID, institution, reference, IBAN, currency, name).
+    # Token management endpoints (usually handled internally)
+    def get_access_token(self) -> SpectacularJWTObtain:
+        """Get a new access token (usually handled internally)"""
+        data = self.post(
+            "/token/new/",
+            data={"secret_id": self.secret_id, "secret_key": self.secret_key},
+        )
+        return SpectacularJWTObtain(**data)
+
+    def refresh_access_token(self, refresh_token: str) -> SpectacularJWTRefresh:
+        """Refresh access token"""
+        data = self.post("/token/refresh/", data={"refresh": refresh_token})
+        return SpectacularJWTRefresh(**data)
+
+    # Integration endpoints
+    def get_integrations(self) -> List[Integration]:
+        """Get all integrations"""
+        data = self.get("/integrations/")
+        return [Integration(**integration) for integration in data]
+
+    def get_integration(self, integration_id: str) -> IntegrationRetrieve:
+        """Get specific integration"""
+        data = self.get(f"/integrations/{integration_id}/")
+        return IntegrationRetrieve(**data)
+
+    # Paginated endpoints with full response models
+    def get_requisitions_paginated(
+        self, limit: Optional[int] = None, offset: Optional[int] = None
+    ) -> PaginatedRequisitionList:
+        """Get paginated requisitions"""
+        params = {}
+        if limit:
+            params["limit"] = limit
+        if offset:
+            params["offset"] = offset
+        data = self.get("/requisitions/", params=params)
+        return PaginatedRequisitionList(**data)
+
+    def get_agreements_paginated(
+        self, limit: Optional[int] = None, offset: Optional[int] = None
+    ) -> PaginatedEndUserAgreementList:
+        """Get paginated agreements"""
+        params = {}
+        if limit:
+            params["limit"] = limit
+        if offset:
+            params["offset"] = offset
+        data = self.get("/agreements/enduser/", params=params)
+        return PaginatedEndUserAgreementList(**data)
+
+    # Convenience methods for common workflows
+    def list_banks(self, country: Optional[str] = None) -> List[str]:
+        """Quick way to list bank names for a country"""
+        institutions = self.get_institutions(country)
+        return [inst.name for inst in institutions]
+
+    def find_requisition_by_reference(self, reference: str) -> Optional[Requisition]:
+        """Find a requisition by its reference"""
+        requisitions = self.get_requisitions()
+        return next((req for req in requisitions if req.reference == reference), None)
+
+    def create_bank_link(
+        self, reference: str, bank_id: str, redirect_url: str = "http://localhost"
+    ) -> Optional[str]:
+        """Create bank link and return the URL"""
+        existing = self.find_requisition_by_reference(reference)
+        if existing:
+            return None
+
+        requisition = self.create_requisition(
+            redirect=redirect_url, institution_id=bank_id, reference=reference
+        )
+        return requisition.link
 
-        Returns:
-            list: A list of dictionaries, each representing a connected account.
-        """
+    def get_all_accounts(self) -> List[AccountInfo]:
+        """Get all accounts from all requisitions"""
         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"),
-                    }
-                )
+        for req in self.get_requisitions():
+            for account_id in req.accounts:
+                try:
+                    account = self.get_account(account_id)
+                    account_dict = account.model_dump()
+                    account_dict.update(
+                        {
+                            "requisition_id": req.id,
+                            "requisition_reference": req.reference,
+                            "institution_id": req.institution_id,
+                        }
+                    )
+                    accounts.append(account_dict)
+                except Exception:
+                    # Skip accounts that can't be accessed
+                    continue
         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", [])