Add Invoice and LineItems endpoints

Author: Jakub Smolar

tests/integration/conftest.py

@@ -11,7 +11,7 @@
 from threescale_api.resources import (Service, ApplicationPlan, Application,
                                       Proxy, Backend, Metric, MappingRule,
                                       BackendMappingRule, BackendUsage,
-                                      ActiveDoc, Webhooks)
+                                      ActiveDoc, Webhooks, InvoiceState)
 
 load_dotenv()
 
@@ -459,3 +459,26 @@ def account_plan(account_plans_params, api):
     entity = api.account_plans.create(params=account_plans_params)
     yield entity
     cleanup(entity)
+
+
+@pytest.fixture(scope="module")
+def invoice(account, api):
+    entity = api.invoices.create(dict(account_id=account['id']))
+    yield entity
+    entity.state_update(InvoiceState.cancelled)
+
+
+@pytest.fixture(scope='module')
+def invoice_line_params():
+    name = f"test-{get_suffix()}"
+    return dict(name=name,
+                description='test_item',
+                quantity='1',
+                cost=10)
+
+
+@pytest.fixture(scope='module')
+def invoice_line(invoice, invoice_line_params, api):
+    entity = invoice.line_items.create(invoice_line_params)
+    yield entity
+    cleanup(entity)

tests/integration/test_integration_invoices.py

@@ -0,0 +1,73 @@
+import pytest
+
+from threescale_api.resources import InvoiceState
+from .asserts import assert_resource, assert_resource_params
+
+
+@pytest.fixture(scope="function")
+def invoice_to_update(account, api):
+    entity = api.invoices.create(dict(account_id=account['id']))
+    yield entity
+    entity.state_update(InvoiceState.cancelled)
+
+
+def test_invoice_create(invoice):
+    assert_resource(invoice)
+
+
+def test_invoice_read(invoice, api):
+    read = api.invoices.read(invoice.entity_id)
+    assert_resource(read)
+    assert_resource_params(read, invoice)
+
+
+def test_invoice_list(invoice, api):
+    invoices = api.invoices.list()
+    assert len(invoices) >= 1
+
+
+def test_invoice_update(invoice, api):
+    assert invoice['state'] == 'open'
+    update = api.invoices.update(invoice.entity_id, dict(friendly_id='1111-11111111'))
+    assert update['friendly_id'] == '1111-11111111'
+    read = api.invoices.read(invoice.entity_id)
+    assert read['friendly_id'] == '1111-11111111'
+
+
+def test_invoice_list_by_account(api, account, invoice):
+    invoices = api.invoices.list_by_account(account.entity_id)
+    assert len(invoices) == 1
+    assert_resource(invoices[0])
+    assert_resource_params(invoice, invoices[0])
+
+
+def test_invoice_read_by_account(api, account, invoice):
+    read = api.invoices.read_by_account(invoice.entity_id, account.entity_id)
+    assert_resource(read)
+    assert_resource_params(read, invoice)
+
+
+def test_invoice_update_state(invoice_to_update, api):
+    assert invoice_to_update['state'] == 'open'
+    update = api.invoices.state_update(invoice_to_update.entity_id, InvoiceState.pending)
+    assert update['state'] == 'pending'
+    read = api.invoices.read(invoice_to_update.entity_id)
+    assert read['state'] == 'pending'
+
+
+def test_invoice_resource_update_state(invoice_to_update, api):
+    assert invoice_to_update['state'] == 'open'
+    update = invoice_to_update.state_update(InvoiceState.pending)
+    assert update['state'] == 'pending'
+    read = api.invoices.read(invoice_to_update.entity_id)
+    assert read['state'] == 'pending'
+
+
+def test_line_invoice_create(invoice_line):
+    assert_resource(invoice_line)
+
+
+def test_line_invoice_list(invoice, invoice_line):
+    lines = invoice.line_items.list()
+    assert len(lines) == 1
+    assert_resource_params(invoice_line, lines[0])

threescale_api/client.py

@@ -40,6 +40,7 @@ def __init__(self, url: str, token: str, throws: bool = True, ssl_verify: bool =
                                                            instance_klass=resources.PolicyRegistry)
         self._backends = resources.Backends(self, instance_klass=resources.Backend)
         self._webhooks = resources.Webhooks(self)
+        self._invoices = resources.Invoices(self, instance_klass=resources.Invoice)
 
     @property
     def rest(self) -> 'RestApiClient':
@@ -204,6 +205,10 @@ def policy_registry(self) -> resources.PolicyRegistry:
     def webhooks(self) -> resources.Webhooks:
         return self._webhooks
 
+    @property
+    def invoices(self) -> resources.Invoices:
+        return self._invoices
+
 
 class RestApiClient:
     def __init__(self, url: str, token: str, throws: bool = True, ssl_verify: bool = True):

threescale_api/resources.py

@@ -1,4 +1,5 @@
 import logging
+from enum import Enum
 from typing import Dict, Union, List, Iterable
 
 from threescale_api import auth
@@ -778,6 +779,71 @@ def clear(self):
         return self.update(params=params)
 
 
+class LineItems(DefaultClient):
+    """Default client for LineItems"""
+    def __init__(self, *args, entity_name='line_item', entity_collection='line_items', **kwargs):
+        super().__init__(*args, entity_name=entity_name,
+                         entity_collection=entity_collection, **kwargs)
+
+    @property
+    def url(self) -> str:
+        return self.parent.url + '/line_items'
+
+
+class InvoiceState(Enum):
+    cancelled, failed, paid, unpaid, pending, finalized = range(6)
+
+
+class Invoices(DefaultClient):
+    """Default client for Invoices"""
+    def __init__(self, *args, entity_name='invoice', entity_collection='invoices', **kwargs):
+        super().__init__(*args, entity_name=entity_name,
+                         entity_collection=entity_collection, **kwargs)
+
+    @property
+    def url(self) -> str:
+        return self.threescale_client.url + '/api/invoices'
+
+    @property
+    def line_items(self) -> LineItems:
+        return LineItems(parent=self, instance_klass=LineItem)
+
+    def list_by_account(self, account: Union['Account', int], **kwargs):
+        account_id = _extract_entity_id(account)
+        url = self.threescale_client.url + f"/api/accounts/{account_id}/invoices"
+        response = self.rest.get(url, **kwargs)
+        instance = self._create_instance(response=response, collection=True)
+        return instance
+
+    def read_by_account(self, entity_id: int, account: Union['Account', int], **kwargs):
+        account_id = _extract_entity_id(account)
+        url = self.threescale_client.url + f"/api/accounts/{account_id}/invoices/{entity_id}"
+        response = self.rest.get(url, **kwargs)
+        instance = self._create_instance(response=response)
+        return instance
+
+    def state_update(self, entity_id: int, state: InvoiceState, **kwargs):
+        """
+        Update the state of the Invoice.
+        Values allowed (depend on the previous state):
+            cancelled, failed, paid, unpaid, pending, finalized
+        """
+        log.info(f"[Invoice] state changed for invoice ({entity_id}): {state}")
+        params = dict(state=state.name)
+        url = self._entity_url(entity_id) + '/state'
+        response = self.rest.put(url=url, json=params, **kwargs)
+        instance = self._create_instance(response=response)
+        return instance
+
+    def charge(self, entity_id: int):
+        """Charge an Invoice."""
+        log.info(f"[Invoice] charge invoice ({entity_id})")
+        url = self._entity_url(entity_id) + '/state'
+        response = self.rest.post(url)
+        instance = self._create_instance(response=response)
+        return instance
+
+
 # Resources
 
 
@@ -1242,3 +1308,23 @@ def unsuspend(self):
     def activate(self):
         log.info("Changes the state of the user of the provider account to active")
         return self.set_state(state='activate')
+
+
+class LineItem(DefaultResource):
+    def __init__(self, entity_name='name', **kwargs):
+        super().__init__(entity_name=entity_name, **kwargs)
+
+
+class Invoice(DefaultResource):
+    def __init__(self, entity_name='friendly_id', **kwargs):
+        super().__init__(entity_name=entity_name, **kwargs)
+
+    @property
+    def line_items(self) -> LineItems:
+        return LineItems(parent=self, instance_klass=LineItem)
+
+    def state_update(self, state: InvoiceState, **kwargs):
+        return self.client.state_update(entity_id=self.entity_id, state=state, **kwargs)
+
+    def charge(self, **kwargs):
+        return self.client.charge(entity_id=self.entity_id, **kwargs)