Add bills

Author: erwindouna

src/pyfirefly/models.py

@@ -254,3 +254,57 @@ class Budget(DataClassORJSONMixin):
     type: str
     id: str
     attributes: BudgetAttributes
+
+
+@dataclass
+class BillPaidDate(DataClassORJSONMixin):
+    """Model for a Firefly bill paid date."""
+
+    transaction_group_id: str | None = None
+    transaction_journal_id: str | None = None
+    date: str | None = None
+
+
+@dataclass
+class BillAttributes(DataClassORJSONMixin):  # pylint: disable=too-many-instance-attributes
+    """Attributes of a Firefly bill."""
+
+    created_at: str | None = None
+    updated_at: str | None = None
+    currency_id: str | None = None
+    currency_code: str | None = None
+    currency_symbol: str | None = None
+    currency_decimal_places: int | None = None
+    native_currency_id: str | None = None
+    native_currency_code: str | None = None
+    native_currency_symbol: str | None = None
+    native_currency_decimal_places: int | None = None
+    name: str | None = None
+    amount_min: str | None = None
+    amount_max: str | None = None
+    native_amount_min: str | None = None
+    native_amount_max: str | None = None
+    date: str | None = None
+    end_date: str | None = None
+    extension_date: str | None = None
+    repeat_freq: str | None = None
+    skip: int | None = None
+    active: bool | None = None
+    order: int | None = None
+    notes: str | None = None
+    next_expected_match: str | None = None
+    next_expected_match_diff: str | None = None
+    object_group_id: str | None = None
+    object_group_order: int | None = None
+    object_group_title: str | None = None
+    pay_dates: list[str] | None = None
+    paid_dates: list[BillPaidDate] | None = None
+
+
+@dataclass
+class Bill(DataClassORJSONMixin):
+    """Model for a Firefly bill."""
+
+    type: str
+    id: str
+    attributes: BillAttributes

src/pyfirefly/pyfirefly.py

@@ -20,7 +20,7 @@
     FireflyNotFoundError,
     FireflyTimeoutError,
 )
-from pyfirefly.models import About, Account, Budget, Category, Transaction
+from pyfirefly.models import About, Account, Bill, Budget, Category, Transaction
 
 try:
     VERSION = metadata.version(__package__)
@@ -253,7 +253,7 @@ async def get_categories(self, category_id: int, start: str | None = None, end:
         return Category.from_dict(category["data"])
 
     async def get_budgets(self, start: str | None = None, end: str | None = None) -> list[Budget]:
-        """Get budgets for the Firefly server.
+        """Get budgets for the Firefly server. Both start and end dates are required for date range filtering.
 
         Args:
             start: The start date for the budgets.
@@ -264,18 +264,42 @@ async def get_budgets(self, start: str | None = None, end: str | None = None) ->
 
         """
         params: dict[str, str] = {}
-        if start:
+        if start and end:
             params["start"] = start
-        if end:
             params["end"] = end
 
         budgets = await self._request(uri="budgets", params=params)
         return [Budget.from_dict(budget) for budget in budgets["data"]]
 
-    @property
-    def api_url(self) -> str:
-        """Return the API URL."""
-        return f"{self._api_scheme}://{self._api_host}:{self._api_port}"
+    async def get_bills(self, start: str | None = None, end: str | None = None) -> list[Bill]:
+        """Get bills for the Firefly server. Both start and end dates are required for date range filtering.
+
+        Args:
+            start: The start date for the bills.
+            end: The end date for the bills.
+
+        Returns:
+            A list of Bill containing bill information.
+
+        """
+        bills: list[dict[str, Any]] = []
+        next_page: int | None = 1
+        params: dict[str, str] = {"page": str(next_page)}
+        if start and end:
+            params["start"] = start
+            params["end"] = end
+
+        while next_page:
+            response = await self._request(uri="bills", params=params)
+            bills.extend(response["data"])
+
+            pagination = response.get("meta", {}).get("pagination", {})
+            current_page = int(pagination.get("current_page", 1) or 1)
+            total_pages = int(pagination.get("total_pages", 1) or 1)
+
+            next_page = current_page + 1 if current_page < total_pages else None
+
+        return [Bill.from_dict(bill) for bill in bills]
 
     async def close(self) -> None:
         """Close open client session."""

tests/__snapshots__/test_models.ambr

@@ -19,6 +19,16 @@
     Account(type='accounts', id='4', attributes=AccountAttributes(created_at='2021-05-10T09:30:00+01:00', updated_at='2022-05-10T09:30:00+01:00', active=True, name='Credit Card', type='liability', account_role='creditCard', currency_id='14', currency_code='GBP', currency_symbol='£', currency_decimal_places=2, native_currency_id='14', native_currency_code='GBP', native_currency_symbol='£', native_currency_decimal_places=2, current_balance='-250.00', native_current_balance='-250.00', current_balance_date='2022-05-10T09:30:00+01:00', order=3, notes='Credit card account', monthly_payment_date='2022-05-15T09:30:00+01:00', credit_card_type='monthlyFull', account_number='9876543210', iban='GB29NWBK60161331926819', bic='NWBKGB2L', virtual_balance='0.00', native_virtual_balance='0.00', opening_balance='0.00', native_opening_balance='0.00', opening_balance_date='2021-05-10T09:30:00+01:00', liability_type='credit', liability_direction='debit', interest='19.99', interest_period='monthly', current_debt='250.00', include_net_worth=False, longitude=0.1278, latitude=51.5074, zoom_level=10, last_activity=None)),
   ])
 # ---
+# name: test_bills_model
+  list([
+    Bill(type='bills', id='2', attributes=BillAttributes(created_at='2018-09-17T12:46:47+01:00', updated_at='2018-09-17T12:46:47+01:00', currency_id='5', currency_code='EUR', currency_symbol='$', currency_decimal_places=2, native_currency_id='5', native_currency_code='EUR', native_currency_symbol='$', native_currency_decimal_places=2, name='Rent', amount_min='123.45', amount_max='123.45', native_amount_min='123.45', native_amount_max='123.45', date='2018-09-17T12:46:47+01:00', end_date='2018-09-17T12:46:47+01:00', extension_date='2018-09-17T12:46:47+01:00', repeat_freq='monthly', skip=0, active=True, order=1, notes='Some example notes', next_expected_match='2018-09-17T12:46:47+01:00', next_expected_match_diff='today', object_group_id='5', object_group_order=5, object_group_title='Example Group', pay_dates=['2018-09-17T12:46:47+01:00'], paid_dates=[BillPaidDate(transaction_group_id='123', transaction_journal_id='123', date='2018-09-17T12:46:47+01:00')])),
+  ])
+# ---
+# name: test_bills_model.1
+  list([
+    Bill(type='bills', id='2', attributes=BillAttributes(created_at='2018-09-17T12:46:47+01:00', updated_at='2018-09-17T12:46:47+01:00', currency_id='5', currency_code='EUR', currency_symbol='$', currency_decimal_places=2, native_currency_id='5', native_currency_code='EUR', native_currency_symbol='$', native_currency_decimal_places=2, name='Rent', amount_min='123.45', amount_max='123.45', native_amount_min='123.45', native_amount_max='123.45', date='2018-09-17T12:46:47+01:00', end_date='2018-09-17T12:46:47+01:00', extension_date='2018-09-17T12:46:47+01:00', repeat_freq='monthly', skip=0, active=True, order=1, notes='Some example notes', next_expected_match='2018-09-17T12:46:47+01:00', next_expected_match_diff='today', object_group_id='5', object_group_order=5, object_group_title='Example Group', pay_dates=['2018-09-17T12:46:47+01:00'], paid_dates=[BillPaidDate(transaction_group_id='123', transaction_journal_id='123', date='2018-09-17T12:46:47+01:00')])),
+  ])
+# ---
 # name: test_budgets_model
   list([
     Budget(type='budgets', id='2', attributes=BudgetAttributes(created_at='2018-09-17T12:46:47+01:00', updated_at='2018-09-17T12:46:47+01:00', name='Bills', active=False, notes='Some notes', order=5, auto_budget_type='reset', currency_id='12', currency_code='EUR', currency_symbol='$', currency_decimal_places=2, native_currency_id='5', native_currency_code='EUR', native_currency_symbol='$', native_currency_decimal_places=2, auto_budget_amount='-1012.12', native_auto_budget_amount='-1012.12', auto_budget_period='monthly', spent=[BudgetSpent(sum='123.45', currency_id='5', currency_code='USD', currency_symbol='$', currency_decimal_places=2)])),

tests/fixtures/bills.json

@@ -0,0 +1,57 @@
+{
+    "data": [
+      {
+        "type": "bills",
+        "id": "2",
+        "attributes": {
+          "created_at": "2018-09-17T12:46:47+01:00",
+          "updated_at": "2018-09-17T12:46:47+01:00",
+          "currency_id": "5",
+          "currency_code": "EUR",
+          "currency_symbol": "$",
+          "currency_decimal_places": 2,
+          "native_currency_id": "5",
+          "native_currency_code": "EUR",
+          "native_currency_symbol": "$",
+          "native_currency_decimal_places": 2,
+          "name": "Rent",
+          "amount_min": "123.45",
+          "amount_max": "123.45",
+          "native_amount_min": "123.45",
+          "native_amount_max": "123.45",
+          "date": "2018-09-17T12:46:47+01:00",
+          "end_date": "2018-09-17T12:46:47+01:00",
+          "extension_date": "2018-09-17T12:46:47+01:00",
+          "repeat_freq": "monthly",
+          "skip": 0,
+          "active": true,
+          "order": 1,
+          "notes": "Some example notes",
+          "next_expected_match": "2018-09-17T12:46:47+01:00",
+          "next_expected_match_diff": "today",
+          "object_group_id": "5",
+          "object_group_order": 5,
+          "object_group_title": "Example Group",
+          "pay_dates": [
+            "2018-09-17T12:46:47+01:00"
+          ],
+          "paid_dates": [
+            {
+              "transaction_group_id": "123",
+              "transaction_journal_id": "123",
+              "date": "2018-09-17T12:46:47+01:00"
+            }
+          ]
+        }
+      }
+    ],
+    "meta": {
+      "pagination": {
+        "total": 3,
+        "count": 20,
+        "per_page": 100,
+        "current_page": 1,
+        "total_pages": 1
+      }
+    }
+  }

tests/test_models.py

@@ -163,4 +163,38 @@ async def test_budgets_model(
     budgets = await firefly_client.get_budgets()
     assert budgets == snapshot
 
-    # Now for all budgets
+
+async def test_bills_model(
+    aresponses: ResponsesMockServer,
+    firefly_client: Firefly,
+    snapshot: SnapshotAssertion,
+) -> None:
+    """Test the Bills model."""
+    aresponses.add(
+        "localhost:9000",
+        "/api/v1/bills",
+        "GET",
+        aresponses.Response(
+            status=200,
+            headers={"Content-Type": "application/vnd.api+json"},
+            text=load_fixtures("bills.json"),
+        ),
+    )
+
+    bills = await firefly_client.get_bills(start="2025-01-01", end="2025-12-31")
+    assert bills == snapshot
+
+    # Now without a date range
+    aresponses.add(
+        "localhost:9000",
+        "/api/v1/bills",
+        "GET",
+        aresponses.Response(
+            status=200,
+            headers={"Content-Type": "application/vnd.api+json"},
+            text=load_fixtures("bills.json"),
+        ),
+    )
+
+    bills = await firefly_client.get_bills()
+    assert bills == snapshot