feat(analytics): Add overdue balance endpoint

lago_python_client/client.py

@@ -13,6 +13,7 @@
 from .invoiced_usages.clients import InvoicedUsageClient
 from .mrrs.clients import MrrClient
 from .organizations.clients import OrganizationClient
+from .overdue_balances.clients import OverdueBalanceClient
 from .invoice_collections.clients import InvoiceCollectionClient
 from .plans.clients import PlanClient
 from .subscriptions.clients import SubscriptionClient
@@ -95,6 +96,10 @@ def mrrs(self) -> MrrClient:
     def organizations(self) -> OrganizationClient:
         return OrganizationClient(self.base_api_url, self.api_key)
 
+    @callable_cached_property
+    def overdue_balances(self) -> OverdueBalanceClient:
+        return OverdueBalanceClient(self.base_api_url, self.api_key)
+
     @callable_cached_property
     def invoice_collections(self) -> InvoiceCollectionClient:
         return InvoiceCollectionClient(self.base_api_url, self.api_key)

lago_python_client/models/gross_revenue.py

@@ -7,6 +7,7 @@ class GrossRevenueResponse(BaseResponseModel):
     amount_cents: Optional[int]
     currency: Optional[str]
     month: str
+    invoices_count: int
 
 
 class GrossRevenuesResponse(BaseResponseModel):

lago_python_client/models/overdue_balance.py

@@ -0,0 +1,14 @@
+from typing import List, Optional
+
+from ..base_model import BaseModel, BaseResponseModel
+
+
+class OverdueBalanceResponse(BaseResponseModel):
+    amount_cents: int
+    currency: str
+    month: str
+    lago_invoice_ids: List[str]
+
+
+class OverdueBalancesResponse(BaseResponseModel):
+    __root__: List[OverdueBalanceResponse]

lago_python_client/overdue_balances/clients.py

@@ -0,0 +1,39 @@
+import sys
+from typing import Any, ClassVar, Type, Union
+
+from ..base_client import BaseClient
+from ..mixins import FindAllCommandMixin
+from ..models.overdue_balance import OverdueBalanceResponse
+from ..services.request import make_headers, make_url, send_get_request
+from ..services.response import get_response_data, prepare_index_response, Response
+
+if sys.version_info >= (3, 9):
+    from collections.abc import Mapping
+else:
+    from typing import Mapping
+
+
+class OverdueBalanceClient(
+    FindAllCommandMixin[OverdueBalanceResponse],
+    BaseClient,
+):
+    API_RESOURCE: ClassVar[str] = 'overdue_balances'
+    RESPONSE_MODEL: ClassVar[Type[OverdueBalanceResponse]] = OverdueBalanceResponse
+    ROOT_NAME: ClassVar[str] = 'overdue_balance'
+
+    def find_all(self, options: Mapping[str, Union[int, str]] = {}) -> Mapping[str, Any]:
+        api_response: Response = send_get_request(
+            url=make_url(
+                origin=self.base_url,
+                path_parts=('analytics', 'overdue_balance'),
+                query_pairs=options,
+            ),
+            headers=make_headers(api_key=self.api_key),
+        )
+
+        # Process response data
+        return prepare_index_response(
+            api_resource=self.API_RESOURCE,
+            response_model=self.RESPONSE_MODEL,
+            data=get_response_data(response=api_response),
+        )

tests/fixtures/gross_revenue_index.json

@@ -3,12 +3,14 @@
     {
       "month": "2023-11-01T00:00:00.000Z",
       "amount_cents": 100,
-      "currency": "EUR"
+      "currency": "EUR",
+      "invoices_count": 1
     },
     {
       "month": "2023-12-01T00:00:00.000Z",
       "amount_cents": 200,
-      "currency": "USD"
+      "currency": "USD",
+      "invoices_count": 2
     }
   ],
   "meta": {}

tests/fixtures/overdue_balance_index.json

@@ -0,0 +1,17 @@
+{
+  "overdue_balances": [
+    {
+      "month": "2023-11-01T00:00:00.000Z",
+      "amount_cents": 100,
+      "currency": "EUR",
+      "lago_invoice_ids": ["1a901a90-1a90-1a90-1a90-1a901a901a90"]
+    },
+    {
+      "month": "2023-12-01T00:00:00.000Z",
+      "amount_cents": 200,
+      "currency": "USD",
+      "lago_invoice_ids": ["1a901a90-1a90-1a90-1a90-1a901a901a90"]
+    }
+  ],
+  "meta": {}
+}

tests/test_gross_revenue_client.py

@@ -25,3 +25,4 @@ def test_valid_find_all_gross_revenues_request(httpx_mock: HTTPXMock):
     assert response['gross_revenues'][0].currency == 'EUR'
     assert response['gross_revenues'][0].amount_cents == 100
     assert response['gross_revenues'][0].month == '2023-11-01T00:00:00.000Z'
+    assert response['gross_revenues'][0].invoices_count == 1

tests/test_overdue_balance_client.py

@@ -0,0 +1,28 @@
+import os
+
+import pytest
+from pytest_httpx import HTTPXMock
+
+from lago_python_client.client import Client
+from lago_python_client.exceptions import LagoApiError
+from lago_python_client.models.overdue_balance import OverdueBalanceResponse
+
+
+def mock_collection_response():
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+    data_path = os.path.join(current_dir, 'fixtures/overdue_balance_index.json')
+
+    with open(data_path, 'rb') as overdue_balances_response:
+        return overdue_balances_response.read()
+
+
+def test_valid_find_all_overdue_balances_request(httpx_mock: HTTPXMock):
+    client = Client(api_key='886fe239-927d-4072-ab72-6dd345e8dd0d')
+
+    httpx_mock.add_response(method='GET', url='https://api.getlago.com/api/v1/analytics/overdue_balance', content=mock_collection_response())
+    response = client.overdue_balances.find_all()
+
+    assert response['overdue_balances'][0].currency == 'EUR'
+    assert response['overdue_balances'][0].amount_cents == 100
+    assert response['overdue_balances'][0].month == '2023-11-01T00:00:00.000Z'
+    assert response['overdue_balances'][0].lago_invoice_ids == ['1a901a90-1a90-1a90-1a90-1a901a901a90']