freeagent 0.1__tar.gz

freeagent-0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Duncan Bellamy
+
+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.

freeagent-0.1/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: freeagent
+Version: 0.1
+Summary: Public class
+Author-email: Duncan Bellamy <dunk@denkimushi.com>
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: requests-oauthlib
+Requires-Dist: coverage ; extra == "dev"
+Requires-Dist: flit ; extra == "dev"
+Requires-Dist: pytest ; extra == "dev"
+Requires-Dist: furo ; extra == "docs"
+Requires-Dist: myst-parser>=2.0 ; extra == "docs"
+Requires-Dist: sphinx>=7.0 ; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints ; extra == "docs"
+Requires-Dist: black ; extra == "lint"
+Requires-Dist: pylint ; extra == "lint"
+Project-URL: Home, https://github.com/a16bitsysop/freeagentPY
+Provides-Extra: dev
+Provides-Extra: docs
+Provides-Extra: lint
+
+# freeagent
+
+`freeagent` is a python library for using the freeagent API.
+
+## Initial setup
+
+Create an API app entry at the [Freeagent Dev Portal](https://dev.freeagent.com)
+
+## Exmple
+
+```python
+from os import environ
+import json
+
+from freeagent import FreeAgent
+
+def _load_token():
+    with open("token.json", "r") as f:
+        token = json.load(f)
+    except (FileNotFoundError, json.JSONDecodeError):
+        token = None
+    return token
+
+def _save_token(token_data):
+    # save the token
+    with open("token.json", "w") as f:
+        json.dump(token_data, f)
+
+client_id = environ["FREEAGENT_ID"]
+client_secret = environ["FREEAGENT_SECRET"]
+
+token = _load_token()
+
+freeagent_client = FreeAgent()
+freeagent_client.authenticate(client_id, client_secret ,_save_token, token)
+
+main_response = freeagent_client.get_api("users/me")
+print(
+f"✅ Authenticated! User info: {main_response['user']['first_name']} {main_response['user']['last_name']}"
+)
+
+paypal_id = freeagent_client.bank.get_first_paypal_id()
+paypal_data = freeagent_client.bank.get_unexplained_transactions(paypal_id)
+```
+
+## Documentation
+
+Full documentation is available at  
+👉 [https://a16bitsysop.github.io/freeagentPY/](https://a16bitsysop.github.io/freeagentPY/)
+
+---
+
+## Running Tests
+
+Run tests:
+
+```bash
+pytest
+```
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repo
+2. Create your feature branch `git checkout -b my-feature`
+3. Edit the source code to add and test your changes
+4. Commit your changes `git commit -m 'Add some feature'`
+5. Push to your branch `git push origin my-feature`
+6. Open a Pull Request
+
+Please follow the existing code style and write tests for new features.
+
+---
+
+## License
+
+This project is licensed under the MIT [MIT License](https://github.com/a16bitsysop/freeagentPY/blob/main/LICENSE).
+
+---
+
+## Contact
+
+Created and maintained by Duncan Bellamy.
+Feel free to open issues or reach out on GitHub.
+
+---
+

freeagent-0.1/README.md

@@ -0,0 +1,87 @@
+# freeagent
+
+`freeagent` is a python library for using the freeagent API.
+
+## Initial setup
+
+Create an API app entry at the [Freeagent Dev Portal](https://dev.freeagent.com)
+
+## Exmple
+
+```python
+from os import environ
+import json
+
+from freeagent import FreeAgent
+
+def _load_token():
+    with open("token.json", "r") as f:
+        token = json.load(f)
+    except (FileNotFoundError, json.JSONDecodeError):
+        token = None
+    return token
+
+def _save_token(token_data):
+    # save the token
+    with open("token.json", "w") as f:
+        json.dump(token_data, f)
+
+client_id = environ["FREEAGENT_ID"]
+client_secret = environ["FREEAGENT_SECRET"]
+
+token = _load_token()
+
+freeagent_client = FreeAgent()
+freeagent_client.authenticate(client_id, client_secret ,_save_token, token)
+
+main_response = freeagent_client.get_api("users/me")
+print(
+f"✅ Authenticated! User info: {main_response['user']['first_name']} {main_response['user']['last_name']}"
+)
+
+paypal_id = freeagent_client.bank.get_first_paypal_id()
+paypal_data = freeagent_client.bank.get_unexplained_transactions(paypal_id)
+```
+
+## Documentation
+
+Full documentation is available at  
+👉 [https://a16bitsysop.github.io/freeagentPY/](https://a16bitsysop.github.io/freeagentPY/)
+
+---
+
+## Running Tests
+
+Run tests:
+
+```bash
+pytest
+```
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repo
+2. Create your feature branch `git checkout -b my-feature`
+3. Edit the source code to add and test your changes
+4. Commit your changes `git commit -m 'Add some feature'`
+5. Push to your branch `git push origin my-feature`
+6. Open a Pull Request
+
+Please follow the existing code style and write tests for new features.
+
+---
+
+## License
+
+This project is licensed under the MIT [MIT License](https://github.com/a16bitsysop/freeagentPY/blob/main/LICENSE).
+
+---
+
+## Contact
+
+Created and maintained by Duncan Bellamy.
+Feel free to open issues or reach out on GitHub.
+
+---

freeagent-0.1/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["flit_scm",]
+build-backend = "flit_scm:buildapi"
+
+[project]
+name = "freeagent"
+authors = [{name = "Duncan Bellamy", email = "dunk@denkimushi.com"}]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+dynamic = ["version", "description"]
+dependencies = [
+    "requests-oauthlib"
+]
+requires-python = ">=3.8"
+
+[project.urls]
+Home = "https://github.com/a16bitsysop/freeagentPY"
+
+[project.optional-dependencies]
+dev = [
+    "coverage",
+    "flit",
+    "pytest",
+]
+lint = [
+    "black",
+    "pylint",
+]
+docs = [
+    "furo",                       # HTML theme
+    "myst-parser>=2.0",           # For Markdown support
+    "sphinx>=7.0",
+    "sphinx-autodoc-typehints",   # For cleaner type hints in docs
+]
+
+[tool.flit.sdist]
+include = ["tests", "src/freeagent/_version.py"]
+
+[tool.setuptools_scm]
+write_to = "src/freeagent/_version.py"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+[tool.pylint.main]
+output-format = "colorized"
+verbose = true
+ignore-patterns = ["_version.py"]

freeagent-0.1/src/freeagent/__init__.py

@@ -0,0 +1,27 @@
+"""
+Public class
+"""
+
+try:
+    from ._version import version as __version__
+except ModuleNotFoundError:
+    # _version.py is written when building dist
+    __version__ = "0.0.0+local"
+
+from .base import FreeAgentBase
+from .bank import BankAPI
+from .category import CategoryAPI
+from .transaction import TransactionAPI
+from .payload import ExplanationPayload
+
+
+class FreeAgent(FreeAgentBase):
+    """
+    The main public class
+    """
+
+    def __init__(self):
+        super().__init__()  # initialse base class
+        self.bank = BankAPI(self)
+        self.category = CategoryAPI(self)
+        self.transaction = TransactionAPI(self)

freeagent-0.1/src/freeagent/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.1'
+__version_tuple__ = version_tuple = (0, 1)
+
+__commit_id__ = commit_id = 'g4a136d763'

freeagent-0.1/src/freeagent/bank.py

@@ -0,0 +1,226 @@
+"""
+This module provides the BankAPI class to retreive information
+about bank accounts on freeagent
+"""
+
+from base64 import b64encode
+from pathlib import Path
+
+from .base import FreeAgentBase
+from .payload import ExplanationPayload
+
+
+class BankAPI(FreeAgentBase):
+    """
+    BankAPI class to retreive information
+    about bank accounts on freeagent
+
+    Initialize the base class
+
+    :param api_base_url: the url to use for requests, defaults to normal but
+        can be changed to sandbox
+    """
+
+    def __init__(self, parent):  # pylint: disable=super-init-not-called
+        """
+        Initialize the BankAPI class
+        """
+        self.parent = parent  # the main FreeAgent instance
+
+    def _check_file_size(self, path: Path) -> int:
+        """
+        Helper funtion to check file size for attaching files to explanations
+
+        :param path: pathlike Path of the file to check
+
+        :return: filesize in bytes
+        :raises ValueError: if the filesize is larger than 5MB (freeagent limit)
+        """
+        max_attachment_size = 5 * 1024 * 1024  # 5 MB
+        size = path.stat().st_size
+        if size > max_attachment_size:
+            raise ValueError(
+                f"Attachment too large ({size} bytes). Max allowed is 5 MB."
+            )
+        return size
+
+    def _encode_file_base64(self, path: Path) -> str:
+        """
+        Encode the passed file as base64 after checking size
+
+        :param path: pathlike Path of the file to encode
+
+        :return: string of the encoded file
+        """
+        self._check_file_size(path)
+        with path.open("rb") as f:
+            return b64encode(f.read()).decode("utf-8")
+
+    def _get_filetype(self, filename: Path) -> str:
+        """
+        Guess the filetype based on dot extension of name
+
+        :param filename: pathlike Path of the file to guess
+
+        :return: string of the filetype
+        :raises ValueError: if file is not a type supported by freeagent
+        """
+        allowed_types = {
+            ".pdf": "application/x-pdf",
+            ".png": "image/x-png",
+            ".jpeg": "image/jpeg",
+            ".jpg": "image/jpeg",
+            ".gif": "image/gif",
+        }
+        # Guess FreeAgent content type
+        content_type = allowed_types.get(filename.suffix.lower())
+        if not content_type:
+            raise ValueError(f"Unsupported file type for FreeAgent: {filename.suffix}")
+
+        return content_type
+
+    def attach_file_to_explanation(
+        self, payload: ExplanationPayload, path: Path, description: str = None
+    ):
+        """
+        Attach a file to an existing ExplanationPayload
+        freeagent supports:
+
+        - image/x-png
+        - image/jpeg
+        - image/jpg
+        - image/gif
+        - application/x-pdf
+
+        :param payload: ExplanationPayload to add the file to
+        :param description: optional description to use for the file on freeagent
+        """
+        file_data = self._encode_file_base64(path)
+        file_type = self._get_filetype(path)
+
+        payload.attachment = {
+            "file_name": path.name,
+            "description": description or "Attachment",
+            "content_type": file_type,
+            "data": file_data,
+        }
+
+    def explain_transaction(self, tx_obj: ExplanationPayload, dryrun: bool = False):
+        """
+        Post the explanation to freeagent in the passed ExplanationPayload tx_obj
+
+        :param tx_obj: ExplanationPayload to use
+        :param dry_run: if True then do not post to freeagent, only print details
+        """
+        json_data = self.serialize_for_api(tx_obj)
+
+        print(json_data["description"], json_data.get("gross_value"))
+        if not dryrun:
+            self.parent.post_api(
+                "bank_transaction_explanations",
+                "bank_transaction_explanation",
+                json_data,
+            )
+
+    def explain_update(
+        self, url: str, tx_obj: ExplanationPayload, dryrun: bool = False
+    ):
+        """
+        Update an existing explanation on freeagent with the passed url
+
+        :param url: url attribute of the bank transaction explanation to change
+        :param tx_obj: ExplanationPayload to use for updating the explanation
+        :param dry_run: if True then do not post to freeagent, only print details
+        """
+        json_data = self.serialize_for_api(tx_obj)
+
+        print(json_data["description"], json_data.get("gross_value"))
+        if not dryrun:
+            self.parent.put_api(url, "bank_transaction_explanation", json_data)
+
+    def get_unexplained_transactions(self, account_id: str) -> list:
+        """
+        Return a list of unexplained transaction objects for the bank account with id of account_id
+
+        :param account_id: account id to use, not the whole url
+
+        :return: list of the unexplained transactions
+        """
+        params = {"bank_account": account_id, "view": "unexplained"}
+        return self.parent.get_api("bank_transactions", params)
+
+    def _find_bank_id(self, bank_accounts: list, account_name: str) -> str:
+        """
+        Get the freeagent bank account ID for account_name
+
+        :param bank_accounts: a list of the bank accounts on freeagent
+        :param account_name: name of the account to find
+
+        :return: the id of the bank account or None if not found
+        """
+        for account in bank_accounts:
+            if account.name.lower() == account_name.lower():
+                return account.url.rsplit("/", 1)[-1]
+        return None
+
+    def get_paypal_id(self, account_name: str) -> str:
+        """
+        Get the ID of PayPal account on freeagent
+
+        :param account_name: name of the account to find
+
+        :return: ID of the named PayPal account or None
+        """
+        params = {"view": "paypal_accounts"}
+        response = self.parent.get_api("bank_accounts", params)
+        return self._find_bank_id(response, account_name)
+
+    def get_first_paypal_id(self) -> str:
+        """
+        Get the ID of the first PayPal account on freeagent
+
+        :return: ID of the first PayPal account or None if there is no PayPal account
+        """
+        params = {"view": "paypal_accounts"}
+        response = self.parent.get_api("bank_accounts", params)
+        if response:
+            return response[0].url.rsplit("/", 1)[-1]
+        return None
+
+    def get_id(self, account_name: str) -> str:
+        """
+        Get the ID of account_name searching standard bank accounts
+
+        :param account_name: name of the account to find
+
+        :return: ID of the account or None if not found
+        """
+        params = {"view": "standard_bank_accounts"}
+        response = self.parent.get_api("bank_accounts", params)
+        return self._find_bank_id(response, account_name)
+
+    def get_primary(self):
+        """
+        Get the ID of the primary bank account on freeagent (current account)
+
+        :return: ID of the account or None if not found
+        """
+        params = {"view": "standard_bank_accounts"}
+        response = self.parent.get_api("bank_accounts", params)
+        for acct in response:
+            if getattr(acct, "is_primary", False):
+                return acct.url.rsplit("/", 1)[-1]
+        return None
+
+    def get_primary_uri(self):
+        """
+        Get the uri for the primary bank account on freeagent (current account)
+
+        :return: uri of the account or None if not found
+        """
+        params = {"view": "standard_bank_accounts"}
+        response = self.parent.get_api("bank_accounts", params)
+        for acct in response:
+            if getattr(acct, "is_primary", False):
+                return acct.url
+        return None

freeagent-0.1/src/freeagent/base.py

@@ -0,0 +1,202 @@
+"""
+Base class the other class inherit from
+"""
+
+from dataclasses import asdict, is_dataclass
+from datetime import date, datetime
+from decimal import Decimal
+from webbrowser import open as open_browser
+
+from requests_oauthlib import OAuth2Session
+
+from .utils import make_dataclass_from_dict
+
+
+class FreeAgentBase:
+    """
+    Common functions used in other classes
+    """
+
+    def __init__(
+        self,
+        api_base_url: str = "https://api.freeagent.com/v2/",
+    ):
+        """
+        Initialize the base class
+
+        :param api_base_url: the url to use for requests, defaults to normal but can be
+            changed to sandbox
+        """
+        self.api_base_url = api_base_url
+        self.session = None
+
+    def authenticate(
+        self, oauth_ident: str, oauth_secret: str, save_token_cb, token: str = None
+    ):
+        """
+        Authenticate with the freeagent API
+
+        :param oauth_ident: oauth identifier from the freeagent dev dashboard
+        :param oauth_secret: oauth secret from the freeagent dev dashboard
+        :param save_token_cb: function to call when the token is refreshed to save it
+        :param token: initial token, or None
+        """
+        token_url = self.api_base_url + "token_endpoint"
+        redirect_uri = "https://localhost/"
+
+        extra = {"client_id": oauth_ident, "client_secret": oauth_secret}
+
+        if token:
+            oauth = OAuth2Session(
+                oauth_ident,
+                token=token,
+                auto_refresh_url=token_url,
+                auto_refresh_kwargs=extra,
+                token_updater=save_token_cb,
+            )
+        elif oauth_secret:
+            oauth = OAuth2Session(
+                oauth_ident, redirect_uri=redirect_uri, scope=[self.api_base_url]
+            )
+            auth_url, _state = oauth.authorization_url(
+                self.api_base_url + "approve_app"
+            )
+            print("🔐 Open this URL and authorise the app:", auth_url)
+            open_browser(auth_url)
+            redirect_response = input("📋 Paste the full redirect URL here: ").strip()
+
+            token = oauth.fetch_token(
+                token_url,
+                authorization_response=redirect_response,
+                client_secret=oauth_secret,
+            )
+            save_token_cb(token)
+        else:
+            raise ValueError("Need oauth_secret, or oauth_token")
+
+        self.session = oauth
+        self.session.headers.update(
+            {
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+            }
+        )
+
+        # Get user info and print it
+        user_info = self.get_api("users/me")
+        first_name = user_info[0].user["first_name"]
+        last_name = user_info[0].user["last_name"]
+        print(f"✅ Authenticated! User info: {first_name} {last_name}")
+        print()
+
+    def serialize_for_api(self, obj) -> dict[str, any]:
+        """
+        Convert dataclasses or dicts with Decimal, date, etc. into plain API-compatible dicts
+
+        :param obj: dataclass or dict to convert
+
+        return: API-compatible dict
+        """
+        if is_dataclass(obj):
+            obj = asdict(obj)
+
+        def convert(val):
+            if isinstance(val, Decimal):
+                return str(val)
+            if isinstance(val, (date, datetime)):
+                return val.isoformat()
+            if isinstance(val, dict):
+                return {k: convert(v) for k, v in val.items()}
+            if isinstance(val, list):
+                return [convert(i) for i in val]
+            return val
+
+        return {k: convert(v) for k, v in obj.items() if v is not None}
+
+    def get_api(self, endpoint: str, params: dict = None) -> list:
+        """
+        Perform an API get request, handling pagination
+
+        :param endpoint: end part of the endpoint URL
+        :param params: dict of "Name": Value entries for request to process into URL
+
+        :return: A list of dataclass instances
+        """
+        if params is None:
+            params = {}
+
+        per_page = 100
+        params["per_page"] = per_page
+        params["page"] = 1
+
+        response = self.session.get(self.api_base_url + endpoint, params=params)
+        response.raise_for_status()
+        json_data = response.json()
+
+        key = endpoint.split("/")[-1]
+        class_name = key.rstrip("s")
+
+        if not isinstance(json_data, dict) or key not in json_data:
+            return [make_dataclass_from_dict(class_name, json_data)]
+
+        items = [
+            make_dataclass_from_dict(class_name, item)
+            for item in json_data.get(key, [])
+        ]
+
+        if len(items) == per_page:
+            page = 2
+            while True:
+                params["page"] = page
+                response = self.session.get(self.api_base_url + endpoint, params=params)
+                response.raise_for_status()
+                json_data = response.json()
+
+                if key in json_data:
+                    current_items = json_data[key]
+                    items.extend(
+                        [
+                            make_dataclass_from_dict(class_name, item)
+                            for item in current_items
+                        ]
+                    )
+
+                    if len(current_items) < per_page:
+                        break
+                else:
+                    break
+
+                page += 1
+
+        return items
+
+    def put_api(self, url: str, root: str, updates: str):
+        """
+        Perform an API put request
+
+        :param url: complete url for put request
+        :param root: first part of payload
+        :param updates: second part of payload
+
+        :raises RunTimeError: if put request fails
+        """
+        payload = {root: updates}
+        response = self.session.put(url, json=payload)
+        if response.status_code != 200:
+            raise RuntimeError(f"PUT failed {response.status_code}: {response.text}")
+
+    def post_api(self, endpoint: str, root: str, payload: str):
+        """
+        Perform an API post request
+
+        :param endpoint: end part of url endpoint
+        :param root: first part of payload
+        :param payload: second part of payload
+
+        :raises RunTimeError: if post request fails
+        """
+        data = {root: payload}
+        response = self.session.post(self.api_base_url + endpoint, json=data)
+        if response.status_code not in (200, 201):
+            raise RuntimeError(f"POST failed {response.status_code}: {response.text}")
+        return response.json()

freeagent-0.1/src/freeagent/category.py

@@ -0,0 +1,82 @@
+"""
+Class for getting freeagent categories
+categories are cached after first run
+"""
+
+from .base import FreeAgentBase
+from .utils import list_to_dataclasses
+
+
+class CategoryAPI(FreeAgentBase):
+    """
+    The CategoryAPI class
+    """
+
+    def __init__(self, parent):  # pylint: disable=super-init-not-called
+        """
+        Initialize the class
+        """
+        self.parent = parent  # the main FreeAgent instance
+        self.categories = []
+
+    def _prep_categories(self):
+        """
+        get the categories if not already done
+        """
+        if self.categories:
+            return
+
+        response = self.parent.get_api("categories")
+        if not response:
+            return
+
+        container = response[0]
+        self.categories = []
+        for value in vars(container).values():
+            if isinstance(value, list):
+                self.categories.extend(list_to_dataclasses("Category", value))
+
+    def get_desc_id(self, description: str) -> str:
+        """
+        Return the category id url for passed category name
+
+        :param description: name of category to find
+
+        :return: id url of the category
+        :raises ValueError: if category not found
+        """
+        self._prep_categories()
+        for cat in self.categories:
+            if description.lower() in cat.description.lower():
+                return cat.url
+        raise ValueError(f"Category with description '{description}' not found.")
+
+    def get_desc_nominal_code(self, description: str) -> str:
+        """
+        Return the nominal code for a given category description
+
+        :param description: The description of the category
+
+        :return: The nominal code of the category
+        :raises ValueError: if category not found
+        """
+        self._prep_categories()
+        for cat in self.categories:
+            if description.lower() in cat.description.lower():
+                return cat.nominal_code
+        raise ValueError(f"Category with description '{description}' not found.")
+
+    def get_nominal_code_id(self, nominal_code: int) -> str:
+        """
+        Get category id url from nominal code
+
+        :param nominal_code: nominal code of category to find
+
+        :return: id url of the category
+        :raises ValueError: if category not found
+        """
+        self._prep_categories()
+        for cat in self.categories:
+            if str(nominal_code) == cat.nominal_code:
+                return cat.url
+        raise ValueError(f"Category with nominal code '{nominal_code}' not found.")

freeagent-0.1/src/freeagent/payload.py

@@ -0,0 +1,23 @@
+"""
+ExplanationPayload dataclass used by this module
+"""
+
+from dataclasses import dataclass
+from datetime import date
+from decimal import Decimal
+from typing import Optional, Dict
+
+
+@dataclass
+class ExplanationPayload:
+    """
+    dataclass used to store data for functions
+    """
+
+    nominal_code: str  # Required
+    dated_on: date  # Required
+    gross_value: Decimal  # Required
+    description: Optional[str] = None  # Optional
+    bank_transaction: Optional[str] = None  # Required for new explanations
+    attachment: Optional[Dict] = None
+    transfer_bank_account: Optional[str] = None

freeagent-0.1/src/freeagent/transaction.py

@@ -0,0 +1,40 @@
+"""
+Class for getting freeagent transactions
+"""
+
+from .base import FreeAgentBase
+
+
+class TransactionAPI(FreeAgentBase):
+    """
+    The TransactionAPI class
+    """
+
+    def __init__(self, parent):  # pylint: disable=super-init-not-called
+        """
+        Initialize the class
+
+        :param api_base_url: the url to use for requests, defaults to normal but
+            can be changed to sandbox
+        """
+        self.parent = parent  # the main FreeAgent instance
+
+    def get_transactions(
+        self, nominal_code: str, start_date: str, end_date: str
+    ) -> list:
+        """
+        Get transactions for a given category nominal code and date range.
+
+        :param nominal_code: The nominal code of the category.
+        :param start_date: Start date of the date range (YYYY-MM-DD).
+        :param end_date: End date of the date range (YYYY-MM-DD).
+
+        :return: A list of Transaction objects.
+        """
+        params = {
+            "nominal_code": nominal_code,
+            "from_date": start_date,
+            "to_date": end_date,
+        }
+
+        return self.parent.get_api("accounting/transactions", params)

freeagent-0.1/src/freeagent/utils.py

@@ -0,0 +1,114 @@
+"""This module provides utility functions for the FreeAgent API client."""
+
+from dataclasses import make_dataclass
+from decimal import Decimal
+from datetime import date, datetime
+from typing import Optional, Any
+import re
+
+
+def _infer_type(value: Any) -> Any:
+    """
+    Infer the type of a value
+
+    :param value: The value to guess the type of
+
+    :return: The type of the value
+    """
+    inferred_type = Any
+    if isinstance(value, int):
+        inferred_type = int
+    elif isinstance(value, float):
+        inferred_type = Decimal
+    elif isinstance(value, str):
+        if re.fullmatch(r"^-?\d+\.\d+$", value):
+            inferred_type = Decimal
+        elif re.fullmatch(r"^\d{4}-\d{2}-\d{2}$", value):
+            inferred_type = date
+        elif re.fullmatch(
+            r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})?$",
+            value,
+        ):
+            inferred_type = datetime
+        else:
+            inferred_type = str
+    elif isinstance(value, dict):
+        inferred_type = dict
+    elif isinstance(value, list):
+        inferred_type = list
+    return inferred_type
+
+
+def _convert_value(value: Any, target_type: Any) -> Any:
+    """
+    Convert a value to a target type
+
+    :param value: The value to convert
+    :param target_type: The type to convert to
+
+    :return: The converted value
+    """
+    if value is None:
+        return None
+    if target_type is Decimal:
+        return Decimal(value)
+    if target_type is date:
+        return datetime.strptime(value, "%Y-%m-%d").date()
+    if target_type is datetime:
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    return value
+
+
+def make_dataclass_from_dict(class_name: str, data: dict, field_types: dict = None):
+    """
+    Dynamically create a dataclass from a dictionary, with optional type conversions.
+
+    :param class_name: The name to use for the dataclass
+    :param data: The data to turn into a dataclass
+    :param field_types: dict of types for the data
+    """
+    if field_types is None:
+        field_types = {}
+
+    inferred_types = {
+        key: _infer_type(value) for key, value in data.items() if key not in field_types
+    }
+    final_field_types = {**inferred_types, **field_types}
+
+    fields_to_create = [
+        (name, Optional[f_type], None)
+        for name, f_type in final_field_types.items()
+        if name.isidentifier()
+    ]
+
+    data_class = make_dataclass(class_name, fields_to_create)
+
+    converted_data = {
+        key: _convert_value(value, final_field_types.get(key))
+        for key, value in data.items()
+        if key in final_field_types
+    }
+
+    return data_class(
+        **{
+            k: v
+            for k, v in converted_data.items()
+            if k in data_class.__dataclass_fields__
+        }
+    )
+
+
+def list_to_dataclasses(class_name: str, data_list: list) -> list:
+    """
+    Convert a list of dictionaries to a list of dataclasses
+
+    :param class_name: name of the dataclass
+    :param data_list: list of dictionaries
+
+    :return: list of dataclasses
+    """
+    return [
+        make_dataclass_from_dict(class_name, item)
+        for item in data_list
+        if isinstance(item, dict)
+    ]

freeagent-0.1/tests/test_bank.py

@@ -0,0 +1,178 @@
+"""
+Unit tests for the BankAPI class using offline dummy data and mocks.
+Covers file handling, transaction explanations, ID lookups, and API integrations.
+"""
+
+# pylint: disable=protected-access, too-few-public-methods
+import unittest
+from unittest.mock import MagicMock
+from pathlib import Path
+import tempfile
+import os
+import base64
+
+# Import BankAPI from bank.py
+from freeagent.bank import BankAPI
+
+
+# Dummy ExplanationPayload class for testing
+class DummyPayload:
+    """
+    Dummy payload class for simulating ExplanationPayload in tests.
+    """
+
+    def __init__(self):
+        self.attachment = {}
+        self.description = "Test"
+        self.gross_value = 123.45
+        self.nominal_code = "250"
+
+
+class BankAPITestCase(unittest.TestCase):
+    """
+    Unit tests for the BankAPI class using MagicMock and dummy data.
+    """
+
+    def setUp(self):
+        # Dummy parent with API methods mocked
+        self.parent = MagicMock()
+        self.api = BankAPI(self.parent)
+
+    def test_check_file_size_allows_small_file(self):
+        """Test that a small file passes file size validation."""
+        with tempfile.NamedTemporaryFile(delete=False) as tmp:
+            tmp.write(b"x" * (1024 * 10))  # 10KB
+            tmp.flush()
+            size = self.api._check_file_size(Path(tmp.name))
+        self.assertEqual(size, 10240)
+        os.unlink(tmp.name)
+
+    def test_check_file_size_raises_on_large(self):
+        """Test that a large file raises a ValueError."""
+        with tempfile.NamedTemporaryFile(delete=False) as tmp:
+            tmp.write(b"x" * (6 * 1024 * 1024))  # 6MB
+            tmp.flush()
+            with self.assertRaises(ValueError):
+                self.api._check_file_size(Path(tmp.name))
+        os.unlink(tmp.name)
+
+    def test_encode_file_base64(self):
+        """Test that file contents are encoded as base64 correctly."""
+        with tempfile.NamedTemporaryFile(delete=False, mode="wb") as tmp:
+            content = b"abc123"
+            tmp.write(content)
+            tmp.flush()
+            b64 = self.api._encode_file_base64(Path(tmp.name))
+
+        self.assertEqual(b64, base64.b64encode(content).decode("utf-8"))
+        os.unlink(tmp.name)
+
+    def test_get_filetype_valid_and_invalid(self):
+        """Test allowed and disallowed file types."""
+        valid = Path("file.pdf")
+        self.assertEqual(self.api._get_filetype(valid), "application/x-pdf")
+        invalid = Path("file.exe")
+        with self.assertRaises(ValueError):
+            self.api._get_filetype(invalid)
+
+    def test_attach_file_to_explanation(self):
+        """Test attaching a file to an explanation payload."""
+        # Prepare a small file
+        with tempfile.NamedTemporaryFile(delete=False) as tmp:
+            tmp.write(b"data")
+            tmp.flush()
+            payload = DummyPayload()
+            self.api._get_filetype = MagicMock(return_value="application/x-pdf")
+            self.api._encode_file_base64 = MagicMock(return_value="ZGF0YQ==")
+            self.api.attach_file_to_explanation(payload, Path(tmp.name), "desc")
+            self.assertIn("file_name", payload.attachment)
+            self.assertEqual(payload.attachment["description"], "desc")
+        os.unlink(tmp.name)
+
+    def test_explain_transaction_dryrun(self):
+        """Test dry-run mode for explaining a transaction."""
+        payload = DummyPayload()
+        self.api.serialize_for_api = MagicMock(
+            return_value={"description": "desc", "gross_value": 111}
+        )
+        self.api.explain_transaction(payload, dryrun=True)
+        self.parent.post_api.assert_not_called()
+
+    def test_explain_transaction_real(self):
+        """Test real mode posts the explanation to parent API."""
+        payload = DummyPayload()
+        self.api.serialize_for_api = MagicMock(
+            return_value={"description": "desc", "gross_value": 111}
+        )
+        self.api.explain_transaction(payload, dryrun=False)
+        self.parent.post_api.assert_called_once()
+
+    def test_explain_update_dryrun(self):
+        """Test dry-run mode for updating an explanation."""
+        payload = DummyPayload()
+        self.api.serialize_for_api = MagicMock(
+            return_value={"description": "desc", "gross_value": 111}
+        )
+        self.api.explain_update("url", payload, dryrun=True)
+        self.parent.put_api.assert_not_called()
+
+    def test_explain_update_real(self):
+        """Test real mode updates the explanation in parent API."""
+        payload = DummyPayload()
+        self.api.serialize_for_api = MagicMock(
+            return_value={"description": "desc", "gross_value": 111}
+        )
+        self.api.explain_update("url", payload, dryrun=False)
+        self.parent.put_api.assert_called_once()
+
+    def test_get_unexplained_transactions(self):
+        """Test retrieval of unexplained transactions."""
+        dummy_return = {"transactions": [1, 2, 3]}
+        self.parent.get_api.return_value = dummy_return
+        result = self.api.get_unexplained_transactions("accid")
+        self.parent.get_api.assert_called_once()
+        self.assertEqual(result, dummy_return)
+
+    def test_get_paypal_id_works(self):
+        """Test finding PayPal account ID by name."""
+        mock_account = MagicMock()
+        mock_account.configure_mock(name="PayPal Account", url="http://x/y/123")
+        self.parent.get_api.return_value = [mock_account]
+        result_id = self.api.get_paypal_id("PayPal Account")
+        self.assertEqual(result_id, "123")
+
+    def test_get_first_paypal_id(self):
+        """Test retrieval of the first PayPal account ID."""
+        mock_account = MagicMock()
+        mock_account.configure_mock(url="http://x/y/456")
+        self.parent.get_api.return_value = [mock_account]
+        result_id = self.api.get_first_paypal_id()
+        self.assertEqual(result_id, "456")
+        self.parent.get_api.return_value = []
+        result_id = self.api.get_first_paypal_id()
+        self.assertIsNone(result_id)
+
+    def test_get_id(self):
+        """Test standard account ID lookup by name."""
+        mock_account = MagicMock()
+        mock_account.configure_mock(name="Test", url="http://x/y/789")
+        self.parent.get_api.return_value = [mock_account]
+        result_id = self.api.get_id("Test")
+        self.assertEqual(result_id, "789")
+
+    def test_get_primary(self):
+        """Test retrieval of the primary bank account ID."""
+        mock_account1 = MagicMock()
+        mock_account1.configure_mock(is_primary=False, url="http://x/y/111")
+        mock_account2 = MagicMock()
+        mock_account2.configure_mock(is_primary=True, url="http://x/y/222")
+        self.parent.get_api.return_value = [mock_account1, mock_account2]
+        result_id = self.api.get_primary()
+        self.assertEqual(result_id, "222")
+        self.parent.get_api.return_value = []
+        result_id = self.api.get_primary()
+        self.assertIsNone(result_id)
+
+
+if __name__ == "__main__":
+    unittest.main()

freeagent-0.1/tests/test_category.py

@@ -0,0 +1,104 @@
+"""
+Unit tests for the CategoryAPI class using offline dummy data and mocks.
+Verifies category caching, lookup by description, and lookup by nominal code.
+"""
+
+# pylint: disable=protected-access, too-few-public-methods
+import unittest
+from dataclasses import dataclass
+from unittest.mock import MagicMock
+
+from freeagent.category import CategoryAPI
+
+
+@dataclass
+class MockContainer:
+    """Mock container to simulate the API response structure."""
+
+    admin_expenses_categories: list
+    income_categories: list
+
+
+class CategoryAPITestCase(unittest.TestCase):
+    """
+    Unit tests for the CategoryAPI class using MagicMock and dummy data.
+    """
+
+    def setUp(self):
+        # Set up a mock parent with get_api
+        self.parent = MagicMock()
+        self.api = CategoryAPI(self.parent)
+
+        # Data as dictionaries, as they come from the "API" container attributes
+        self.cat1 = {
+            "description": "Office Costs",
+            "url": "http://cat/1",
+            "nominal_code": "101",
+        }
+        self.cat2 = {
+            "description": "Travel",
+            "url": "http://cat/2",
+            "nominal_code": "202",
+        }
+        self.cat3 = {
+            "description": "Old Office",
+            "url": "http://cat/3",
+            "nominal_code": "303",
+        }
+
+        self.container = MockContainer(
+            admin_expenses_categories=[self.cat1, self.cat2],
+            income_categories=[self.cat3],
+        )
+
+        # get_api returns a list containing the container
+        self.parent.get_api.return_value = [self.container]
+
+    def test_prep_categories_fetches_once(self):
+        """Test that categories are fetched from the parent once and then cached."""
+        self.api._prep_categories()
+
+        # Verify the categories were flattened and converted
+        self.assertEqual(len(self.api.categories), 3)
+        descriptions = sorted([c.description for c in self.api.categories])
+        expected_descriptions = sorted(["Office Costs", "Travel", "Old Office"])
+        self.assertEqual(descriptions, expected_descriptions)
+
+        # Should not call get_api again if already cached
+        self.api._prep_categories()
+        self.parent.get_api.assert_called_once_with("categories")
+
+    def test_get_desc_id_finds_description(self):
+        """Test category lookup by description (case-insensitive, substring match)."""
+        url = self.api.get_desc_id("office costs")
+        self.assertEqual(url, "http://cat/1")
+        url = self.api.get_desc_id("Old office")
+        self.assertEqual(url, "http://cat/3")
+        # Case insensitive, substring match
+        url = self.api.get_desc_id("Travel")
+        self.assertEqual(url, "http://cat/2")
+        # Not found
+        with self.assertRaises(ValueError):
+            self.api.get_desc_id("Nonexistent")
+
+    def test_get_nominal_id_finds_code(self):
+        """Test category lookup by nominal code."""
+        url = self.api.get_nominal_code_id(101)
+        self.assertEqual(url, "http://cat/1")
+        url = self.api.get_nominal_code_id(303)
+        self.assertEqual(url, "http://cat/3")
+        with self.assertRaises(ValueError):
+            self.api.get_nominal_code_id(999)
+
+    def test_caching_persists_for_getters(self):
+        """Test that cached categories persist across lookups."""
+        # First call populates cache
+        self.api.get_desc_id("Travel")
+        # Change return value; should not affect already-cached results
+        self.parent.get_api.return_value = []
+        url = self.api.get_desc_id("Office")
+        self.assertEqual(url, "http://cat/1")
+
+
+if __name__ == "__main__":
+    unittest.main()

freeagent-0.1/tests/test_transaction.py

@@ -0,0 +1,44 @@
+"""
+Unit tests for the TransactionAPI class using offline dummy data and mocks.
+"""
+
+# pylint: disable=protected-access, too-few-public-methods
+import unittest
+from unittest.mock import MagicMock
+
+from freeagent.transaction import TransactionAPI
+
+
+class TransactionAPITestCase(unittest.TestCase):
+    """
+    Unit tests for the TransactionAPI class using MagicMock and dummy data.
+    """
+
+    def setUp(self):
+        # Set up a mock parent with get_api
+        self.parent = MagicMock()
+        self.api = TransactionAPI(self.parent)
+
+    def test_get_transactions_success(self):
+        """Test that transactions are fetched correctly for a valid category."""
+        nominal_code = "123"
+        start_date = "2023-01-01"
+        end_date = "2023-01-31"
+        expected_transactions = {"transactions": ["transaction1", "transaction2"]}
+        self.parent.get_api.return_value = expected_transactions
+
+        transactions = self.api.get_transactions(nominal_code, start_date, end_date)
+
+        self.parent.get_api.assert_called_once_with(
+            "accounting/transactions",
+            {
+                "nominal_code": nominal_code,
+                "from_date": start_date,
+                "to_date": end_date,
+            },
+        )
+        self.assertEqual(transactions, expected_transactions)
+
+
+if __name__ == "__main__":
+    unittest.main()