tariochbctools 1.3.0__tar.gz → 1.4.0__tar.gz

{tariochbctools-1.3.0 → tariochbctools-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tariochbctools
-Version: 1.3.0
+Version: 1.4.0
 Summary: Importers, plugins and price fetchers for Beancount
 Home-page: https://github.com/tarioch/beancounttools/
 Author: Patrick Ruckstuhl
@@ -20,6 +20,7 @@ Classifier: License :: OSI Approved :: MIT License
 Description-Content-Type: text/x-rst; charset=UTF-8
 License-File: LICENSE.txt
 Requires-Dist: importlib-metadata; python_version < "3.8"
+Requires-Dist: awardwallet
 Requires-Dist: beancount>=3
 Requires-Dist: beangulp
 Requires-Dist: beanprice

{tariochbctools-1.3.0 → tariochbctools-1.4.0}/docs/importers.rst

@@ -443,3 +443,52 @@ Import PDF from `radicant <https://radicant.com/>`__
   from tariochbctools.importers.radicant import importer as radicant
 
   CONFIG = [radicant.Importer("Account.*\.pdf", "Assets:Radicant")]
+
+AwardWallet
+------------------------------
+
+Import from `AwardWallet <https://awardwallet.com/>`__ using their `Account Access API <https://awardwallet.com/api/account>`__.
+
+As of 2025 AwardWallet integrates over 460 airline, hotel, shopping and other loyalty programmes.
+
+Follow the instructions in the `API documentation <https://awardwallet.com/api/account#introduction>`__ to register for a free Business account and create an API key.
+
+The API key is restricted to the **allowed IP addresses** you specify in the Business interface API Settings.
+
+Link and authorize personal accounts using the included ``awardwallet-conf`` CLI tool:
+
+.. code-block:: console
+
+  awardwallet-conf --api-key YOUR_API_KEY get_link_url
+
+
+Generate a config file for all linked users called (or ending with) ``awardwallet.yaml`` in your import location (e.g. download folder) and edit it to your needs.
+Note that not all providers support retrieval of transaction history.
+
+.. code-block:: console
+
+  awardwallet-conf --api-key YOUR_API_KEY generate > awardwallet.yaml
+
+Example configuration file:
+
+.. code-block:: yaml
+
+  api_key: YOUR_API_KEY
+  users:
+    12345:
+      name: John Smith
+      all_history: false
+      accounts:
+        7654321:
+          provider: "British Airways Club"
+          account: Assets:Current:Points
+          currency: AVIOS
+
+
+Finally, initialize the importer:
+
+.. code-block:: python
+
+  from tariochbctools.importers.awardwalletimp import importer as awimp
+
+  CONFIG = [awimp.Importer()]

{tariochbctools-1.3.0 → tariochbctools-1.4.0}/setup.cfg

@@ -29,6 +29,7 @@ package_dir =
 	=src
 install_requires = 
 	importlib-metadata; python_version<"3.8"
+	awardwallet
 	beancount>=3
 	beangulp
 	beanprice
@@ -61,6 +62,7 @@ testing =
 [options.entry_points]
 console_scripts = 
 	nordigen-conf = tariochbctools.importers.nordigen.nordigen_config:run
+	awardwallet-conf = tariochbctools.importers.awardwalletimp.config:run
 
 [test]
 extras = True

tariochbctools-1.4.0/src/tariochbctools/importers/awardwalletimp/config.py

@@ -0,0 +1,93 @@
+import argparse
+import sys
+import uuid
+from typing import Any
+
+import yaml
+from awardwallet import AwardWalletClient
+from awardwallet.api import AccessLevel
+
+
+def get_link_url(client):
+    connection_url = client.get_connection_link(
+        platform="desktop",
+        access_level=AccessLevel.READ_ALL_EXCEPT_PASSWORDS,
+        state=str(uuid.uuid4()),
+    )
+    print(  # noqa: T201
+        "Redirect your user to this URL to authorize the connection."
+        "\nThis link expires in 10 minutes:"
+    )
+    print(connection_url)  # noqa: T201
+
+
+def generate(client):
+    """
+    Generate a config for a user including user_id and account_id list.
+    Output in yaml format.
+    """
+    config = {}
+    config["api_key"] = client.api_key
+    config["users"] = {}
+
+    connected_users = client.list_connected_users()
+
+    for user in connected_users:
+        user_id = user["userId"]
+        user_details = client.get_connected_user_details(user_id)
+        account_config = {}
+
+        for account in user_details.get("accounts", []):
+            account_config[account["accountId"]] = {
+                "provider": account["displayName"],
+                "account": "Assets:Current:Points",  # Placeholder, user should adjust
+                "currency": "POINTS",
+            }
+
+        config["users"][user_id] = {
+            "name": user["userName"],
+            "all_history": False,
+            "accounts": account_config,
+        }
+
+    yaml.dump(config, sys.stdout, sort_keys=False)
+
+
+def parse_args(args: Any) -> Any:
+    parser = argparse.ArgumentParser(description="awardwallet-config")
+    sub_parsers = parser.add_subparsers(dest="mode", required=True)
+
+    parser.add_argument(
+        "--api-key",
+        required=True,
+        help="API key, can be generated on AwardWallet Business interface",
+    )
+
+    sub_parsers.add_parser(
+        "get_link_url", help="Generate a connection link URL for user authorization"
+    )
+    sub_parsers.add_parser(
+        "generate", help="Generate a configuration template for connected users"
+    )
+
+    return parser.parse_args(args)
+
+
+def main(args: Any) -> None:
+    args = parse_args(args)
+
+    client = AwardWalletClient(args.api_key)
+
+    if args.mode == "get_link_url":
+        get_link_url(client)
+    elif args.mode == "generate":
+        generate(client)
+
+
+def run() -> None:
+    """Entry point for console_scripts"""
+    main(sys.argv[1:])
+
+
+if __name__ == "__main__":
+    main(sys.argv[1:])

tariochbctools-1.4.0/src/tariochbctools/importers/awardwalletimp/importer.py

@@ -0,0 +1,160 @@
+import logging
+from os import path
+from typing import Any
+
+import beangulp
+import dateutil.parser
+import yaml
+from awardwallet import AwardWalletClient
+from beancount.core import amount, data
+from beancount.core.number import D
+
+
+class Importer(beangulp.Importer):
+    """An importer for AwardWallet"""
+
+    def _configure(self, filepath: str, existing: data.Entries) -> None:
+        with open(filepath, "r") as f:
+            self.config = yaml.safe_load(f)
+        self.api_key = self.config["api_key"]
+
+    def identify(self, filepath: str) -> bool:
+        return path.basename(filepath).endswith("awardwallet.yaml")
+
+    def account(self, filepath: str) -> data.Account:
+        return ""
+
+    def extract(self, filepath: str, existing: data.Entries = None) -> data.Entries:
+        self._configure(filepath, existing)
+        client = AwardWalletClient(self.api_key)
+        entries = []
+
+        for user_id, user in self.config["users"].items():
+            user_details = client.get_connected_user_details(user_id)
+
+            if user.get("accounts"):
+                if user.get("all_history", False):
+                    entries.extend(self._extract_account_history(user, client))
+                else:
+                    entries.extend(self._extract_user_history(user, user_details))
+            else:
+                logging.warning(
+                    "Ignoring user ID %s: no accounts configured",
+                    user_id,
+                )
+
+        return entries
+
+    def _extract_user_history(
+        self, user: dict, user_details: dict
+    ) -> list[data.Transaction]:
+        """
+        User history is limited to the last 10 history elements per account
+        """
+        entries = []
+        for account in user_details["accounts"]:
+            account_id = account["accountId"]
+
+            if account_id in user["accounts"]:
+                logging.info("Extracting account ID %s", account_id)
+                account_config = user["accounts"][account_id]
+
+                entries.extend(
+                    self._extract_transactions(
+                        account["history"], account_config, account_id
+                    )
+                )
+            else:
+                logging.warning(
+                    "Ignoring account ID %s: %s", account_id, account["displayName"]
+                )
+        return entries
+
+    def _extract_account_history(
+        self, user: dict, client: AwardWalletClient
+    ) -> list[data.Transaction]:
+        entries = []
+        for account_id, account_config in user["accounts"].items():
+            logging.info("Extracting account ID %s", account_id)
+            account = client.get_account_details(account_id)["account"]
+
+            entries.extend(
+                self._extract_transactions(
+                    account["history"], account_config, account_id
+                )
+            )
+        return entries
+
+    def _extract_transactions(
+        self,
+        history: list,
+        account_config: dict,
+        account_id: str,
+    ) -> list[data.Transaction]:
+        local_account = account_config["account"]
+        currency = account_config["currency"]
+
+        logging.debug(
+            "Extracting %i transactions for account %s",
+            len(history),
+            account_id,
+        )
+
+        entries = []
+        for trx in history:
+            entries.extend(
+                self._extract_transaction(trx, local_account, currency, account_id)
+            )
+        return entries
+
+    def _extract_transaction(
+        self,
+        trx: dict[str, Any],
+        local_account: data.Account,
+        currency: str,
+        account_id: str,
+    ) -> list[data.Transaction]:
+        entries = []
+        metakv = {"account-id": str(account_id)}
+
+        trx_date = None
+        trx_description = None
+        trx_amount = None
+
+        for f in trx.get("fields", []):
+            if f["code"] == "PostingDate":
+                trx_date = dateutil.parser.parse(f["value"]["value"]).date()
+            if f["code"] == "Description":
+                trx_description = f["value"]["value"].replace("\n", " ")
+            if f["code"] == "Miles":
+                trx_amount = D(f["value"]["value"])
+            if f["code"] == "Info":
+                name = f["name"].lower().replace(" ", "-")
+                metakv[name] = f["value"]["value"].replace("\n", " ")
+
+        assert trx_date
+        assert trx_description
+        assert trx_amount is not None, f"No amount in trx: {trx}"
+
+        meta = data.new_metadata("", 0, metakv)
+        entry = data.Transaction(
+            meta,
+            trx_date,
+            "*",
+            "",
+            trx_description,
+            data.EMPTY_SET,
+            data.EMPTY_SET,
+            [
+                data.Posting(
+                    local_account,
+                    amount.Amount(trx_amount, currency),
+                    None,
+                    None,
+                    None,
+                    None,
+                ),
+            ],
+        )
+        entries.append(entry)
+        return entries

{tariochbctools-1.3.0 → tariochbctools-1.4.0}/src/tariochbctools.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tariochbctools
-Version: 1.3.0
+Version: 1.4.0
 Summary: Importers, plugins and price fetchers for Beancount
 Home-page: https://github.com/tarioch/beancounttools/
 Author: Patrick Ruckstuhl
@@ -20,6 +20,7 @@ Classifier: License :: OSI Approved :: MIT License
 Description-Content-Type: text/x-rst; charset=UTF-8
 License-File: LICENSE.txt
 Requires-Dist: importlib-metadata; python_version < "3.8"
+Requires-Dist: awardwallet
 Requires-Dist: beancount>=3
 Requires-Dist: beangulp
 Requires-Dist: beanprice

{tariochbctools-1.3.0 → tariochbctools-1.4.0}/src/tariochbctools.egg-info/SOURCES.txt

@@ -27,6 +27,9 @@ src/tariochbctools.egg-info/not-zip-safe
 src/tariochbctools.egg-info/requires.txt
 src/tariochbctools.egg-info/top_level.txt
 src/tariochbctools/importers/__init__.py
+src/tariochbctools/importers/awardwalletimp/__init__.py
+src/tariochbctools/importers/awardwalletimp/config.py
+src/tariochbctools/importers/awardwalletimp/importer.py
 src/tariochbctools/importers/bcge/__init__.py
 src/tariochbctools/importers/bcge/importer.py
 src/tariochbctools/importers/bitst/__init__.py
@@ -81,6 +84,7 @@ tests/__init__.py
 tests/conftest.py
 tests/tariochbctools/__init__.py
 tests/tariochbctools/importers/__init__.py
+tests/tariochbctools/importers/test_awardwallet.py
 tests/tariochbctools/importers/test_quickfile.py
 tests/tariochbctools/importers/test_truelayer.py
 tests/tariochbctools/plugins/__init__.py

{tariochbctools-1.3.0 → tariochbctools-1.4.0}/src/tariochbctools.egg-info/entry_points.txt

@@ -1,2 +1,3 @@
 [console_scripts]
+awardwallet-conf = tariochbctools.importers.awardwalletimp.config:run
 nordigen-conf = tariochbctools.importers.nordigen.nordigen_config:run

{tariochbctools-1.3.0 → tariochbctools-1.4.0}/src/tariochbctools.egg-info/requires.txt

@@ -1,3 +1,4 @@
+awardwallet
 beancount>=3
 beangulp
 beanprice

tariochbctools-1.4.0/tests/tariochbctools/importers/test_awardwallet.py

@@ -0,0 +1,315 @@
+import json
+from unittest.mock import MagicMock, patch
+
+import pytest
+from beancount.core.number import D
+
+from tariochbctools.importers.awardwalletimp import importer as awimp
+
+# pylint: disable=protected-access
+
+TEST_CONFIG = b"""
+    api_key: deadc0dedeadc0dedeadc0dedeadc0de
+    users:
+      12:
+        name: John Smith
+        all_history: false
+        accounts:
+          7654321:
+            provider: "British Airways Club"
+            account: Assets:Current:Points
+            currency: AVIOS
+          6543210:
+            provider: "Virgin Atlantic Club"
+            account: Assets:Current:Points
+            currency: VIRGINPTS
+      34:
+        name: User with dummy account
+        accounts:
+          0:
+"""
+
+TEST_TRX = b"""
+    {
+      "fields": [
+        {
+          "name": "Transaction Date",
+          "code": "PostingDate",
+          "value": {"value": "9/30/12", "type": "string"}
+        },
+        {
+          "name": "Description",
+          "code": "Description",
+          "value": {"value": "Expired Points", "type": "string"}
+        },
+        {
+          "name": "Type",
+          "code": "Info",
+          "value": {"value": "Adjustments", "type": "string"}
+        },
+        {
+          "name": "Points",
+          "code": "Miles",
+          "value": {"value": "-1,042", "type": "miles"}
+        }
+      ]
+    }
+"""
+
+TEST_USER_DETAILS = b"""
+    {
+      "userId": 12,
+      "fullName": "John Smith",
+      "status": "Free",
+      "userName": "JSmith",
+      "email": "JSmith@email.com",
+      "forwardingEmail": "JSmith@AwardWallet.com",
+      "accessLevel": "Regular",
+      "connectionType": "Connected",
+      "accountsAccessLevel": "Full control",
+      "accountsSharedByDefault": true,
+      "editConnectionUrl": "https://business.awardwallet.com/members/connection/112233",
+      "accountListUrl": "https://business.awardwallet.com/account/list#/?agentId=112233",
+      "timelineUrl": "https://business.awardwallet.com/timeline/?agentId=166765#/112233",
+      "bookingRequestsUrl": "https://business.awardwallet.com/awardBooking/queue?user_filter=332211",
+      "accounts": [
+        {
+          "accountId": 7654321,
+          "code": "british",
+          "displayName": "British Airways (Executive Club)",
+          "kind": "Airlines",
+          "login": "johnsmith",
+          "autologinUrl": "https://business.awardwallet.com/account/redirect?ID=7654321",
+          "updateUrl": "https://business.awardwallet.com/account/edit/7654321?autosubmit=1",
+          "editUrl": "https://business.awardwallet.com/account/edit/7654321",
+          "balance": "146,780",
+          "balanceRaw": 146780,
+          "owner": "John Smith",
+          "errorCode": 1,
+          "lastDetectedChange": "+750",
+          "expirationDate": "2018-12-10T00:00:00+00:00",
+          "lastRetrieveDate": "2016-01-15T00:00:00+00:00",
+          "lastChangeDate": "2016-01-15T00:49:33+00:00",
+          "properties": [
+            {
+              "name": "Next Elite Level",
+              "value": {"value": "Bronze", "type": "string"},
+              "kind": 9
+            },
+            {
+              "name": "Date of joining the club",
+              "value": {"value": "20 Jun 2013", "type": "string"},
+              "kind": 5
+            },
+            {
+              "name": "Lifetime Tier Points",
+              "value": {"value": "35,000", "type": "string"}
+            },
+            {
+              "name": "Executive Club Tier Points",
+              "value": {"value": "35,000", "type": "string"}
+            },
+            {
+              "name": "Card expiry date",
+              "value": {"value": "31 Mar 2017", "type": "string"}
+            },
+            {
+              "name": "Membership year ends",
+              "value": {"value": "08 Feb 2016", "type": "string"}
+            },
+            {
+              "name": "Last Activity",
+              "value": {"value": "10-Dec-15", "type": "string"},
+              "kind": 13
+            },
+            {
+              "name": "Name",
+              "value": {"value": "Mr Smith", "type": "string"},
+              "kind": 12
+            },
+            {
+              "name": "Level",
+              "value": {"value": "Blue", "type": "string"},
+              "rank": 0,
+              "kind": 3
+            },
+            {
+              "name": "Membership no",
+              "value": {"value": "1122334455", "type": "string"},
+              "kind": 1
+            }
+          ],
+          "history": [
+            {
+              "fields": [
+                {
+                  "name": "Transaction Date",
+                  "code": "PostingDate",
+                  "value": {"value": "3/31/14", "type": "string"}
+                },
+                {
+                  "name": "Description",
+                  "code": "Description",
+                  "value": {"value": "Expired Points", "type": "string"}
+                },
+                {
+                  "name": "Type",
+                  "code": "Info",
+                  "value": {"value": "Adjustments", "type": "string"}
+                },
+                {
+                  "name": "Points",
+                  "code": "Miles",
+                  "value": {"value": "-100", "type": "miles"}
+                }
+              ]
+            },
+            {
+              "fields": [
+                {
+                  "name": "Transaction Date",
+                  "code": "PostingDate",
+                  "value": {"value": "12/11/13", "type": "string"}
+                },
+                {
+                  "name": "Description",
+                  "code": "Description",
+                  "value": {"value": "Google Wallet", "type": "string"}
+                },
+                {
+                  "name": "Type",
+                  "code": "Info",
+                  "value": {"value": "Other Earning", "type": "string"}
+                },
+                {
+                  "name": "Points",
+                  "code": "Miles",
+                  "value": {"value": "+100", "type": "miles"}
+                }
+              ]
+            },
+            {
+              "fields": [
+                {
+                  "name": "Transaction Date",
+                  "code": "PostingDate",
+                  "value": {"value": "9/30/12", "type": "string"}
+                },
+                {
+                  "name": "Description",
+                  "code": "Description",
+                  "value": {"value": "Expired Points", "type": "string"}
+                },
+                {
+                  "name": "Type",
+                  "code": "Info",
+                  "value": {"value": "Adjustments", "type": "string"}
+                },
+                {
+                  "name": "Points",
+                  "code": "Miles",
+                  "value": {"value": "-1,042", "type": "miles"}
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "accountId": 6543210,
+          "code": "virgin",
+          "displayName": "Virgin Atlantic (Flying Club)",
+          "kind": "Airlines",
+          "balance": "146,780",
+          "balanceRaw": 146780,
+          "owner": "John Smith",
+          "errorCode": 1,
+          "lastDetectedChange": "+750",
+          "properties": [
+            {
+              "name": "Next Elite Level",
+              "value": {"value": "Bronze", "type": "string"},
+              "kind": 9
+            }
+          ],
+          "history": [
+          ]
+        }
+      ]
+    }
+"""
+
+
+@pytest.fixture(name="tmp_config")
+def tmp_config_fixture(tmp_path):
+    config = tmp_path / "awardwallet.yaml"
+    config.write_bytes(TEST_CONFIG)
+    yield config
+
+
+@pytest.fixture(name="importer")
+def awardwallet_importer_fixture(tmp_config):
+    importer = awimp.Importer()
+    importer._configure(tmp_config, [])
+    yield importer
+
+
+@pytest.fixture(name="importer_factory")
+def awardwallet_importer_factory(tmp_path):
+    """A awardwallet importer factory for
+    generating an importer with a custom config
+    """
+
+    def _importer_with_config(custom_config):
+        config = tmp_path / "awardwallet.yaml"
+        config.write_bytes(custom_config)
+        importer = awimp.Importer()
+        importer._configure(config, [])
+        return importer
+
+    yield _importer_with_config
+
+
+@pytest.fixture(name="tmp_trx")
+def tmp_trx_fixture():
+    yield json.loads(TEST_TRX)
+
+
+@pytest.fixture(name="tmp_user_details")
+def tmp_user_details_fixture():
+    yield json.loads(TEST_USER_DETAILS, strict=False)
+
+
+def test_identify(importer, tmp_config):
+    assert importer.identify(tmp_config)
+
+
+def test_extract_transaction_simple(importer, tmp_trx):
+    entries = importer._extract_transaction(tmp_trx, "Assets:Other", "POINTS", 7654321)
+    assert entries[0].postings[0].units.number == D(
+        tmp_trx["fields"][3]["value"]["value"]
+    )
+
+
+def test_extract_user_history(importer, tmp_user_details):
+    entries = importer._extract_user_history(
+        importer.config["users"][12],
+        tmp_user_details,
+    )
+    assert len(entries) == 3
+
+
+@patch("tariochbctools.importers.awardwalletimp.importer.AwardWalletClient")
+def test_extract_all_users(mock_api, importer, tmp_config, tmp_user_details):
+    importer._extract_user_history = MagicMock()
+
+    importer.extract(tmp_config)
+    assert importer._extract_user_history.call_count == 2
+
+
+@patch("tariochbctools.importers.awardwalletimp.importer.AwardWalletClient")
+def test_extract_all_accounts(mock_api, importer, tmp_config, tmp_user_details):
+    importer._extract_transactions = MagicMock()
+    mock_api.return_value.get_connected_user_details.return_value = tmp_user_details
+
+    importer.extract(tmp_config)
+    assert importer._extract_transactions.call_count == 2