Rethink API model and method naming

- carefully consider the true meaning of api endpoints, despite their naming
- rename models and method names for better meaning
- rename and explain all the clients!
- fix renames in tests, marimo notebook, readme
- upgrade marimo

Author: eidorb

README.md

@@ -29,15 +29,15 @@ Create a script named `balances.py`:
 ```python
 from getpass import getpass
 
-from ubank import Api, Passkey
+from ubank import Client, Passkey
 
 # Load passkey from file.
 with open("passkey.txt", "rb") as f:
     passkey = Passkey.load(f, password=getpass("Enter ubank password: "))
 
 # Print account balances.
-with Api(passkey) as api:
-    for account in api.get_accounts().linkedBanks[0].accounts:
+with Client(passkey) as client:
+    for account in client.get_linked_banks().linkedBanks[0].accounts:
         print(
             f"{account.label} ({account.type}): {account.balance.available} {account.balance.currency}"
         )
@@ -58,7 +58,7 @@ Savings account (SAVINGS): 1577.17 AUD
 - [Getting started](#getting-started)
 - [Contents](#contents)
 - [ubank CLI](#ubank-cli)
-- [ubank API](#ubank-api)
+- [ubank API client](#ubank-api-client)
 - [Example web application](#example-web-application)
 - [How to set up a development environment](#how-to-set-up-a-development-environment)
 - [How to test](#how-to-test)
@@ -90,32 +90,32 @@ You will be asked for your ubank password and secret code interactively. The pas
 ```
 
 
-## ubank API
+## ubank API client
 
-The `ubank.Api` class provides a number of methods for accessing ubank's API:
+Create an instance of `ubank.Client` to access ubank's API:
 
 ```python
 from datetime import date
 from getpass import getpass
 
-from ubank import Api, Passkey, TransactionsSearchBody
+from ubank import Client, Filter, Passkey
 
 with open("passkey.txt", "rb") as f:
     passkey = Passkey.load(f, password=getpass("Enter ubank password: "))
 
-with Api(passkey) as api:
-    api.post_accounts_transactions_search(
-        body=TransactionsSearchBody(fromDate=date(2025, 1, 1), toDate=date(2025, 2, 1))
+with Client(passkey) as client:
+    client.summarise_transactions(
+        body=Filter(fromDate=date(2025, 1, 1), toDate=date(2025, 2, 1))
     )
-    bank = api.get_accounts().linkedBanks[0]
-    api.get_account_transactions(
+    bank = client.get_linked_banks().linkedBanks[0]
+    client.search_account_transactions(
         account_id=bank.accounts[0].id,
         bank_id=bank.bankId,
-        customerId=api.get_customer_details().customerId,
+        customerId=client.get_customer_details().customerId,
     )
-    api.get_cards()
-    api.get_devices(deviceUuid=passkey.device_id)
-    api.get_contacts()
+    client.get_cards()
+    client.get_devices(deviceUuid=passkey.device_id)
+    client.get_contacts()
 ```
 
 

notebook.py

@@ -17,7 +17,6 @@
 @app.cell
 def _():
     import marimo as mo
-
     return (mo,)
 
 
@@ -145,7 +144,7 @@ def _(
     password,
     uploaded_passkey,
 ):
-    from ubank import Api
+    from ubank import Client
 
     if create_client.value:
         try:
@@ -155,8 +154,8 @@ def _(
                     io.BytesIO(uploaded_passkey.contents() or new_passkey_file.getvalue()),
                     password.value,
                 )
-                api = Api(passkey)
-                devices = api.get_devices(deviceUuid=passkey.device_id)
+                client = Client(passkey)
+                devices = client.get_devices(deviceUuid=passkey.device_id)
             mo.output.append(
                 mo.md(
                     f"""
@@ -172,7 +171,7 @@ def _(
             )
         except InvalidToken:
             pass
-    return Api, api, devices, passkey
+    return Client, client, devices, passkey
 
 
 @app.cell
@@ -190,24 +189,24 @@ def _(mo):
 
 
 @app.cell
-def _(api, get_balances, mo):
+def _(client, get_balances, mo):
     if get_balances.value:
         with mo.status.spinner():
-            accounts_response = api.get_accounts()
+            bank = client.get_linked_banks().linkedBanks[0]
         mo.output.append(
             mo.tree(
                 [
                     account.model_dump(include={"number", "label", "type", "balance"})
-                    for account in accounts_response.linkedBanks[0].accounts
+                    for account in bank.accounts
                 ]
             )
         )
-    return (accounts_response,)
+    return (bank,)
 
 
 @app.cell
 def _(mo):
-    from ubank import TransactionsSearchBody
+    from ubank import Filter
 
     search_transactions = mo.ui.run_button(label="Search")
     from_date = mo.ui.date()
@@ -223,28 +222,15 @@ def _(mo):
         Limit the number of results to {limit}.
         """
     )
-    return (
-        TransactionsSearchBody,
-        from_date,
-        limit,
-        search_transactions,
-        to_date,
-    )
+    return Filter, from_date, limit, search_transactions, to_date
 
 
 @app.cell
-def _(
-    TransactionsSearchBody,
-    api,
-    from_date,
-    mo,
-    search_transactions,
-    to_date,
-):
+def _(Filter, client, from_date, mo, search_transactions, to_date):
     if search_transactions.value:
         with mo.status.spinner():
-            search_response = api.post_accounts_transactions_search(
-                body=TransactionsSearchBody(fromDate=from_date.value, toDate=to_date.value)
+            search_response = client.summarise_transactions(
+                body=Filter(fromDate=from_date.value, toDate=to_date.value)
             )
         mo.output.append(
             mo.ui.table(

tests/test_ubank.py

@@ -5,10 +5,10 @@
 from httpx import HTTPStatusError
 
 from ubank import (
-    Api,
+    Client,
+    Filter,
     Passkey,
     SoftWebauthnDevice,
-    TransactionsSearchBody,
     __version__,
     add_passkey,
     int8array_to_bytes,
@@ -155,8 +155,8 @@ def test_add_passkey_bad_username():
         assert "Username invalid" in e.__notes__[0]
 
 
-def test_api():
-    """Tests declared API methods using passkey loaded from passkey.txt."""
+def test_client():
+    """Tests declared API endpoint methods using passkey loaded from passkey.txt."""
     # Skip test if hard-coded passkey file is not available.
     try:
         with open("passkey.txt", "rb") as f:
@@ -165,39 +165,33 @@ def test_api():
         pytest.skip(str(e))
 
     # Authenticate to ubank with passkey.
-    with Api(passkey) as api:
+    with Client(passkey) as client:
         assert (
-            api.client.get("accounts").json()["linkedBanks"][0]["accounts"][0][
+            client.client.get("accounts").json()["linkedBanks"][0]["accounts"][0][
                 "balance"
             ]["currency"]
             == "AUD"
         )
 
-        customer = api.get_customer_details()
+        customer = client.get_customer_details()
         assert customer.addresses[0].addressFormat == "AUS"
-        accounts = api.get_accounts()
-        assert accounts.linkedBanks[0].accounts[0].balance.currency == "AUD"
-        assert (
-            api.get_accounts_summary().linkedBanks[0].accounts[0].balance.currency
-            == "AUD"
-        )
-        assert api.post_accounts_transactions_search(
-            body=TransactionsSearchBody(
-                fromDate=date(2024, 1, 1), toDate=date(2025, 1, 1), limit=100
-            )
+        banks = client.get_linked_banks().linkedBanks
+        assert banks[0].accounts[0].balance.currency == "AUD"
+        assert client.summarise_transactions(
+            body=Filter(fromDate=date(2024, 1, 1), toDate=date(2025, 1, 1), limit=100)
         )
-        for account in accounts.linkedBanks[0].accounts:
-            assert api.get_account_transactions(
+        for account in banks[0].accounts:
+            assert client.search_account_transactions(
                 account_id=account.id,
-                bank_id=accounts.linkedBanks[0].bankId,
+                bank_id=banks[0].bankId,
                 customerId=customer.customerId,
             )
-        assert api.get_cards()
+        assert client.get_cards()
         # Name of a device should match this passkey.
         assert [
             device
-            for device in api.get_devices(deviceUuid=passkey.device_id)
+            for device in client.get_devices(deviceUuid=passkey.device_id)
             if device.deviceName == passkey.name
         ]
-        assert api.delete_device(device_id="test-2f9ae784c84d")
-        assert api.get_contacts()
+        assert client.delete_device(device_id="test-2f9ae784c84d")
+        assert client.get_contacts()